DEV Community

Cover image for Deploying BookStack - Open-Source Documentation Platform
Vultr profile image Sanskriti Harmukh
Sanskriti Harmukh for Vultr

Posted on with Aashish Chaurasiya Originally published at docs.vultr.com

Deploying BookStack - Open-Source Documentation Platform

#docker #selfhosted #documentation #traefik

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
Enter fullscreen mode Exit fullscreen mode

2. Navigate to the project directory:

$ cd ~/bookstack
Enter fullscreen mode Exit fullscreen mode

3. Generate a secret key for the BookStack application:

$ echo "base64:$(openssl rand -base64 32)"
Enter fullscreen mode Exit fullscreen mode

Save the output for use in the environment file.

4. Create an environment file:

$ nano .env
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

4. Verify that the services are running:

$ docker compose ps
Enter fullscreen mode Exit fullscreen mode

The output displays all the containers in the Up state.

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

$ docker compose logs
Enter fullscreen mode Exit fullscreen mode

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.

BookStack initial login screen

  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.

BookStack Dashboard screen

  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.

BookStack shelf screen

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.

BookStack Book screen

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.

BookStack chapter screen

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.

BookStack page screen

  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.

Top comments (0)