Self-Hosting BookStack Wiki on a VPS with Docker Compose

This guide walks you through deploying BookStack, a popular opinionated wiki and documentation platform, using Docker Compose on a Virtual Private Server (VPS).

Docker Compose Configuration

version: "3.8"

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - APP_URL=https://wiki.yourdomain.com
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=secure_db_password_here
      - DB_DATABASE=bookstackapp
    volumes:
      - ./bookstack_app_data:/config
    ports:
      - 8080:80
    restart: unless-stopped
    depends_on:
      - bookstack_db

  bookstack_db:
    image: lscr.io/linuxserver/mariadb:latest
    container_name: bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - MYSQL_ROOT_PASSWORD=secure_root_password_here
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=secure_db_password_here
    volumes:
      - ./bookstack_db_data:/config
    restart: unless-stopped

Database and Application Bindings

BookStack requires a database connection to store metadata, users, permissions, and page structure. The environment variables in the Docker Compose file bind the application container to the database container:

1. Host-to-Container Linking: The DB_HOST variable is set to bookstack_db. Docker Compose automatically configures a default bridge network, resolving container names as hostnames.
2. Database Authentication: The values for DB_USER, DB_PASS, and DB_DATABASE in the bookstack service match the MYSQL_USER, MYSQL_PASSWORD, and MYSQL_DATABASE configurations in the bookstack_db service.
3. Volume Persistence: Data is persisted outside the container lifetimes using local directory bindings:
4. ./bookstack_app_data maps to /config in the application container, storing uploaded files, themes, and configuration overrides.
5. ./bookstack_db_data maps to /config in the MariaDB container, storing the actual database schemas and tables.

Deploying the Services

To initiate the deployment, ensure Docker and Docker Compose are installed on your VPS.

1. Create a dedicated directory and navigate to it: bash mkdir -p /opt/bookstack && cd /opt/bookstack
2. Copy the docker-compose.yml code block above into a file named docker-compose.yml. Update the passwords and target domain name (APP_URL).
3. Start the containers in detached mode: bash docker compose up -d
4. Verify both containers are running and healthy: bash docker compose ps

Configuring a Reverse Proxy (Nginx)

To enable SSL/TLS certificates and serve BookStack on standard HTTPS ports, configure a reverse proxy such as Nginx.

Create an Nginx configuration file at /etc/nginx/sites-available/bookstack:

server {
    listen 80;
    server_name wiki.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name wiki.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/wiki.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wiki.yourdomain.com/privkey.pem;

    client_max_body_size 100M; # Match bookstack config for file uploads

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the configuration and reload Nginx:

ln -s /etc/nginx/sites-available/bookstack /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Post-Installation Steps

1. Access BookStack through your configured domain or IP.
2. Log in using the default credentials:
3. Username: admin@admin.com
4. Password: password
5. Immediately navigate to Edit Profile to change your password and email address.

Backup and Maintenance Operations

Creating a Database Backup

Run mysqldump within the running database container:

docker exec bookstack_db mysqldump -u bookstack -psecure_db_password_here bookstackapp > /opt/bookstack/backups/db_backup_$(date +%F).sql

Backing up Application Files

Create an archive of the configuration and uploads directory:

tar -czf /opt/bookstack/backups/app_backup_$(date +%F).tar.gz /opt/bookstack/bookstack_app_data

Upgrading BookStack

To upgrade to the latest stable release:

docker compose pull
docker compose up -d