Skip to main content

Step-by-Step Guide: Setup Bookstack

GitHub-logo.pngicon.png

BookStack is a simple and powerful documentation platform that can be easily deployed using Docker. In this guide, we will set up BookStack on a 3-node Docker Swarm cluster with data stored in a GlusterFS volume. This setup will also utilize Traefik as a reverse proxy with Let's Encrypt for SSL certificates. For more information on setting up Traefik, check out this guide.

Step 1: Create Directories for BookStack Data

Before starting the BookStack containers, you need to create directories where BookStack will store its data. Since we're using GlusterFS to manage our distributed storage, you'll need to create these directories on the shared GlusterFS mount on each node.

mkdir /mnt/glustermount/data/bookstack_data
mkdir /mnt/glustermount/data/bookstack_data/app
mkdir /mnt/glustermount/data/bookstack_data/db

 

Step 2: Set Up the Docker Compose File

Below is the docker-compose.yml file that defines the BookStack application and its database (MariaDB). This file is customized to work with GlusterFS for data storage, Traefik for reverse proxy management, and Let's Encrypt for automatic SSL certificates.

version: "3.7"

services:
  bookstack:
    image: linuxserver/bookstack:arm64v8-24.05.3  # BookStack Docker image for ARMv8
    container_name: bookstack
    environment:
      - APP_URL=https://YOUR-APP-URL.tld  # Set your public-facing URL here
      - TZ=Europe/Zurich  # Set your timezone
      - DB_HOST=192.168.0.200  # Set the host IP where MariaDB is running
      - DB_PORT=3306  # MySQL port
      - DB_DATABASE=${BOOKSTACK_DATABASE}  # Name of the BookStack database
      - DB_USERNAME=${BOOKSTACK_MYSQL_USER}  # MySQL username for BookStack
      - DB_PASSWORD=${BOOKSTACK_MYSQL_PASSWORD}  # MySQL password for BookStack
    volumes:
      - /mnt/glustermount/data/bookstack_data/app:/config  # Mount GlusterFS for BookStack app data
    ports:
      - 6875:80  # Expose port 80 for web access
    restart: unless-stopped  # Restart the container unless it is manually stopped
    depends_on:
      - bookstack_db  # BookStack depends on the MariaDB container
    networks:
     - management_net  # Management network for internal communication
    deploy:
      mode: replicated  # Run BookStack in replicated mode in Docker Swarm
      replicas: 1  # Set the number of replicas (in this case, 1)
      labels:
        - 'traefik.enable=true'  # Enable Traefik for this service
        - 'traefik.http.routers.bookstack.rule=Host(`YOUR-APP-URL.tld`)'  # Set Traefik rule to use the public URL
        - 'traefik.http.routers.bookstack.entrypoints=websecure'  # Use the "websecure" entry point (HTTPS)
        - 'traefik.http.routers.bookstack.tls.certresolver=leresolver'  # Use Let's Encrypt resolver for TLS
        - 'traefik.http.services.bookstack.loadbalancer.server.port=80'  # BookStack uses port 80 internally

  bookstack_db:
    image: mariadb:latest  # MariaDB image for the database
    container_name: bookstack_db
    environment:
      - TZ=Europe/Zurich  # Set your timezone
      - MYSQL_ROOT_PASSWORD=${BOOKSTACK_PASSWORD}  # Root password for MariaDB
      - MYSQL_DATABASE=${BOOKSTACK_DATABASE}  # Database name for BookStack
      - MYSQL_USER=${BOOKSTACK_MYSQL_USER}  # MySQL username for BookStack
      - MYSQL_PASSWORD=${BOOKSTACK_MYSQL_PASSWORD}  # MySQL password for BookStack
    volumes:
      - /mnt/glustermount/data/bookstack_data/db:/var/lib/mysql  # Mount GlusterFS for database data
    ports:
      - 3306:3306  # Expose port 3306 for MySQL access
    restart: unless-stopped  # Restart the container unless manually stopped
    deploy:
      mode: replicated  # Run MariaDB in replicated mode in Docker Swarm
      replicas: 1  # Set the number of replicas (in this case, 1)

networks:
  management_net:
    external: true  # External management network
Explanation of Key Lines in the Docker Compose File:

  • /mnt/glustermount/data/bookstack_data/app:/config: This mounts the GlusterFS volume to the container's /config directory, ensuring that BookStack's data (such as uploads and configurations) is persistent across nodes.

  • APP_URL=https://YOUR-APP-URL.tld: This sets the public-facing URL for BookStack. Replace YOUR-APP-URL.tld with your actual domain. It's important for proper routing and Traefik integration.

  • DB_HOST=192.168.0.200: This specifies the IP address of the database host. In this example, MariaDB is running on the same GlusterFS VIP that keeps the nodes synced.

Composefile without Comments 
version: "3.7"

services:
  bookstack:
    image: linuxserver/bookstack:arm64v8-24.05.3
    container_name: bookstack
    environment:
      - APP_URL=https://YOUR-APP-URL.tld
      - TZ=Europe/Zurich
      - DB_HOST=192.168.0.200
      - DB_PORT=3306
      - DB_DATABASE=${BOOKSTACK_DATABASE}
      - DB_USERNAME=${BOOKSTACK_MYSQL_USER}
      - DB_PASSWORD=${BOOKSTACK_MYSQL_PASSWORD}
    volumes:
      - /mnt/glustermount/data/bookstack_data/app:/config
    ports:
      - 6875:80
    restart: unless-stopped
    depends_on:
      - bookstack_db
    networks:
     - management_net
    deploy:
      mode: replicated
      replicas: 1
      labels:
        - 'traefik.enable=true'
        - 'traefik.http.routers.bookstack.rule=Host(`YOUR-APP-URL.tld`)'
        - 'traefik.http.routers.bookstack.entrypoints=websecure'
        - 'traefik.http.routers.bookstack.tls.certresolver=leresolver'
        - 'traefik.http.services.bookstack.loadbalancer.server.port=80'

  bookstack_db:
    image: mariadb:latest
    container_name: bookstack_db
    environment:
      - TZ=Europe/Zurich
      - MYSQL_ROOT_PASSWORD=${BOOKSTACK_PASSWORD}
      - MYSQL_DATABASE=${BOOKSTACK_DATABASE}
      - MYSQL_USER=${BOOKSTACK_MYSQL_USER}
      - MYSQL_PASSWORD=${BOOKSTACK_MYSQL_PASSWORD}
    volumes:
      - /mnt/glustermount/data/bookstack_data/db:/var/lib/mysql
    ports:
      - 3306:3306
    restart: unless-stopped
    deploy:
      mode: replicated
      replicas: 1

networks:
  management_net:
    external: true

 

 

Step 4: Deploy BookStack

To deploy the stack, navigate to the directory where you saved the docker-compose.yml file and run the following command:

docker stack deploy -c docker-compose.yml bookstack

Or run your Stack in Portainer WebGUI.

This command will deploy both BookStack and the MariaDB container on your Docker Swarm cluster.

 

Step 5: Access BookStack

  • Once the deployment is complete, you can access BookStack at http://dockerhost:6875. The default credentials are:

    • Username: admin@admin.com
    • Password: password


 

Additional Notes

  • Database Setup: If you do not already have a MySQL or MariaDB database, this setup includes the creation of a MariaDB container that BookStack will use.

  • SSL/TLS Certificates: This setup includes labels to work with Traefik and Let's Encrypt to automatically generate and manage SSL certificates. Make sure you have Traefik set up properly by following this guide.

  • Persistent Data: All BookStack and database data is stored in the GlusterFS-mounted directories, ensuring that the data is accessible and replicated across all nodes in your Swarm cluster.

Back to top