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:
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

 

Additional Environment Variables

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


Additional Notes

Revision #10
Created 8 September 2024 14:24:08 by aeoneros
Updated 8 January 2025 11:12:15 by aeoneros