How to Deploy BookStack - Open-Source Documentation Platform

BookStack is an open-source documentation platform for creating, organizing, and managing knowledge bases. It provides a web interface for structuring documentation into Shelves, Books, Chapters, and Pages, making it easy to organize technical documentation, internal wikis, project documentation, and team knowledge.

This article explains how to deploy BookStack on a Linux server using Docker Compose with MariaDB for data storage and Traefik as the reverse proxy for TLS termination. It covers directory and environment setup, the Docker Compose deployment, the initial server setup, and demonstrates documentation management features by creating Shelves, Books, Chapters, and Pages through the web interface.

Prerequisites

Before you begin, you need to:

• Have access to a Linux-based server (with at least 4 CPU cores and 8 GB of RAM) as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Create a DNS A record pointing to your server's IP address (for example, book.example.com).

Set Up the Directory Structure, Configuration, and Environment Variables

BookStack requires a configuration file to define environment variables, database connections, and application settings. The setup includes persistent storage for the MariaDB database, uploaded files, and application configuration to ensure data is retained across server restarts.

1. Create the project directory.

   CONSOLE

   Copy

   $ mkdir ~/bookstack

   Explain Code

   Powered by Vultr AgentBeta

2. Navigate to the project directory.

   CONSOLE

   Copy

   $ cd ~/bookstack

   Explain Code

   Powered by Vultr AgentBeta

3. Generate a secret key for the BookStack application.

   CONSOLE

   Copy

   $ echo "base64:$(openssl rand -base64 32)"

   Explain Code

   Powered by Vultr AgentBeta

   Save the output for use in the environment file.

4. Create an environment file.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

5. Add the following configuration.

   INI

   Copy

   DOMAIN=book.example.com
   LETSENCRYPT_EMAIL=admin@example.com
   
   # BookStack Settings
   APP_URL=https://book.example.com
   APP_KEY=YOUR_GENERATED_APP_KEY
   
   # Database Settings
   DB_DATABASE=bookstack
   DB_USERNAME=bookstack
   DB_PASSWORD=STRONG_DATABASE_PASSWORD_1
   DB_ROOT_PASSWORD=STRONG_DATABASE_PASSWORD_2
   
   # Time Zone
   TZ=UTC

   Explain Code

   Powered by Vultr AgentBeta

   Replace:

   • book.example.com with your domain name.
   • admin@example.com with your email address.
   • YOUR_GENERATED_APP_KEY with the output from the earlier step.
   • STRONG_DATABASE_PASSWORD_1 and STRONG_DATABASE_PASSWORD_2 with two different secure passwords.

   Save and close the file.

Deploy with Docker Compose

The deployment stack uses Traefik as the reverse proxy for TLS termination and deploys BookStack and MariaDB containers with mounted application and database volumes. This configuration is based on the official BookStack Docker Compose configuration.

1. Create the Docker Compose manifest file.

   CONSOLE

   Copy

   $ nano docker-compose.yaml

   Explain Code

   Powered by Vultr AgentBeta

2. Add the following configuration.

   YAML

   Copy

   services:
     traefik:
       image: traefik:v3.7.11
       container_name: traefik
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
         - "--entrypoints.web.http.redirections.entryPoint.scheme=https"
         - "--certificatesresolvers.myresolver.acme.tlschallenge=true"
         - "--certificatesresolvers.myresolver.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock:ro
         - ./letsencrypt:/letsencrypt
       restart: unless-stopped
   
     mariadb:
       image: lscr.io/linuxserver/mariadb:11.8.8
       container_name: bookstack_mariadb
       env_file:
         - .env
       environment:
         - PUID=1000
         - PGID=1000
         - TZ=${TZ}
         - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
         - MYSQL_DATABASE=${DB_DATABASE}
         - MYSQL_USER=${DB_USERNAME}
         - MYSQL_PASSWORD=${DB_PASSWORD}
       volumes:
         - ./bookstack_data/mariadb_data:/config
       restart: unless-stopped
   
     bookstack:
       image: lscr.io/linuxserver/bookstack:version-v26.05.4
       container_name: bookstack
       depends_on:
         - mariadb
       env_file:
         - .env
       environment:
         - PUID=1000
         - PGID=1000
         - TZ=${TZ}
         - APP_URL=${APP_URL}
         - APP_KEY=${APP_KEY}
         - DB_HOST=mariadb
         - DB_PORT=3306
         - DB_DATABASE=${DB_DATABASE}
         - DB_USERNAME=${DB_USERNAME}
         - DB_PASSWORD=${DB_PASSWORD}
       volumes:
         - ./bookstack_data/app_data:/config
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.bookstack.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.bookstack.entrypoints=websecure"
         - "traefik.http.routers.bookstack.tls.certresolver=myresolver"
         - "traefik.http.services.bookstack.loadbalancer.server.port=80"
       restart: unless-stopped

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   In the above manifest:

   • traefik: Serves as the reverse proxy and TLS termination point, using the official Traefik image. It exposes ports 80 and 443 for HTTP and HTTPS traffic, stores certificates in the ./letsencrypt directory, and automatically provisions them through Let's Encrypt.
   • mariadb: Stores the BookStack database, including users, Shelves, Books, Chapters, Pages, and application data, using the LinuxServer.io MariaDB image. The database name, username, password, and root password come from the .env file, and the data persists in the ./bookstack_data/mariadb_data directory.
   • bookstack: Runs the BookStack web application, using the LinuxServer.io BookStack image, and starts only after the mariadb service is available. The application URL, application key, database connection settings, and time zone come from the .env file, the application configuration and uploaded files persist in the ./bookstack_data/app_data directory, and the Traefik labels route HTTPS requests for your domain to this container.

   All three services use restart: unless-stopped, so they restart automatically if they fail or the server reboots.

3. Start all services in detached mode.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

4. Verify that the services are running.

   CONSOLE

   Copy

   $ docker compose ps

   Explain Code

   Powered by Vultr AgentBeta

   The output displays all the containers in the Up state.

5. View the service logs to confirm all components started successfully.

   CONSOLE

   Copy

   $ docker compose logs

   Explain Code

   Powered by Vultr AgentBeta

Access and Configure BookStack

BookStack provides a web interface for organizing and managing documentation using shelves, books, and pages. The dashboard provides a central place to manage your documentation and workspace.

1. Open your web browser and navigate to BookStack at https://book.example.com, replacing book.example.com with your configured domain.

   

2. On the screen, enter Email as admin@admin.com and Password as password to create the admin account.

3. Click Log In to access the BookStack dashboard.

   

4. To change the login password, click the Admin menu in the top-right navigation and select My Account. Then, under the My Account menu on the left, select Access & Security. From here, you can change your password and configure Multi-Factor Authentication (MFA).

Build and Organize Your Documentation in BookStack

BookStack organizes documentation into a hierarchy that makes related content easy to manage and navigate. This workflow creates a Shelf, builds a Book and Chapter within it, and adds a Page containing sample documentation to validate the setup and demonstrate the platform's core features.

Create a Shelf

A Shelf serves as the top-level container for organizing related Books within a documentation collection.

1. Click Shelves in the top navigation menu.

2. Click Create one now or New Shelf under the Actions panel.

3. Enter a shelf name, such as Team Documentation, and an optional description.

4. Click Save Shelf.

   

Create a Book within the Shelf

A Book groups related Chapters and Pages together within a Shelf.

1. Open the Team Documentation shelf you created in the previous step.

2. Click Create New Book.

3. Enter a book name, such as Employee Onboarding, and an optional description.

4. Click Save Book.

   

Create a Chapter within the Book

Chapters organize related Pages into logical sections within a Book.

1. Open the Employee Onboarding book you created in the previous step.

2. Click Add a chapter.

3. Enter a chapter name, such as Getting Started, and an optional description.

4. Click Save Chapter.

   

Create and Edit a Page within the Chapter

Pages are where you create, edit, and organize documentation using the built-in rich text editor.

1. Open the Getting Started chapter you created in the previous step.

2. Click Create a new page.

3. Enter a page title such as Development Environment Setup.

4. Add a brief introduction, followed by a heading titled Prerequisites.

5. Add a bulleted list describing the required software and tools.

6. Click Save Page.

   

7. Reopen the Development Environment Setup page, click Edit under the Actions panel, and add another heading named Next Steps, then click Save Page again.

Conclusion

You have deployed BookStack on a Linux server using Docker Compose and configured data storage and TLS termination. This creates a documentation platform for organizing knowledge into Shelves, Books, Chapters, and Pages. For more information and advanced configuration, see the official BookStack documentation.