Deploying 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 guide deploys BookStack on a Linux server using Docker Compose with MariaDB for data storage and Traefik as the reverse proxy for TLS termination, then walks through creating Shelves, Books, Chapters, and Pages through the web interface. By the end, you'll have a working BookStack instance with a sample documentation hierarchy served securely over HTTPS.

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:

$ mkdir ~/bookstack

2. Navigate to the project directory:

$ cd ~/bookstack

3. Generate a secret key for the BookStack application:

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

Save the output for use in the environment file.

4. Create an environment file:

$ nano .env

5. Add the following configuration:

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

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:

$ nano docker-compose.yaml

2. Add the following configuration:

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

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:

$ docker compose up -d

4. Verify that the services are running:

$ docker compose ps

The output displays all the containers in the Up state.

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

$ docker compose logs

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.

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

2. Click Log In to access the BookStack dashboard.

1. 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.

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

Next Steps

• Invite additional users and configure role-based permissions for each Shelf or Book
• Enable a search index and explore BookStack's built-in page revision history
• Configure an external authentication provider such as LDAP or SAML for team sign-in
• Set up scheduled backups of the MariaDB database and the uploaded file storage

For the full guide with additional tips, visit the original article on Vultr Docs.