Host BookStack on your own VPS

Why self-host BookStack on a VPS

Concrete benefits of a self-hosted BookStack

• Clear structure of shelves/books/chapters/pages: effortlessly navigable documentation.
• WYSIWYG and Markdown editor of your choice, with integrated Draw.io diagrams.
• Granular permissions by role and by book to partition sensitive content.
• Fast full-text search across the entire knowledge base.
• LDAP, SAML or OAuth authentication to integrate with your enterprise directory.
• Lightweight footprint: a VPS with 2 GB of RAM is enough for team documentation.
• No per-user subscription — as many contributors as needed at no extra cost.

Hardware and software prerequisites

BookStack vs self-hosted alternatives

Scroll the table

Deploy BookStack with Docker Compose and SSL

1. 01

   Prepare the VPS and install Docker

   Connect via SSH then install Docker and the Compose plugin:

   curl -fsSL https://get.docker.com | sh
   apt install docker-compose-plugin
   mkdir -p /opt/bookstack && cd /opt/bookstack

   Verify: docker compose version should show v2.x or higher. The community image lscr.io/linuxserver/bookstack is the most widely used and best maintained for containerized deployment.

2. 02

   Create the docker-compose.yml file

   Create /opt/bookstack/docker-compose.yml with two services — MariaDB and BookStack — on a dedicated network:

   services:
     mariadb:
       image: mariadb:10.11
       environment:
         MYSQL_ROOT_PASSWORD: changeme_root
         MYSQL_DATABASE: bookstack
         MYSQL_USER: bookstack
         MYSQL_PASSWORD: changeme_bk
       volumes:
         - ./data/mariadb:/var/lib/mysql
       networks: [bookstack]
   
     bookstack:
       image: lscr.io/linuxserver/bookstack:latest
       environment:
         PUID: 1000
         PGID: 1000
         APP_URL: https://wiki.yourdomain.com
         DB_HOST: mariadb
         DB_USER: bookstack
         DB_PASS: changeme_bk
         DB_DATABASE: bookstack
         MAIL_DRIVER: smtp
         MAIL_HOST: smtp.yourdomain.com
         MAIL_PORT: 587
         MAIL_FROM: [email protected]
         MAIL_USERNAME: [email protected]
         MAIL_PASSWORD: your_smtp_password
       ports:
         - "6875:80"
       volumes:
         - ./data/bookstack:/config
       depends_on: [mariadb]
       networks: [bookstack]
   
   networks:
     bookstack:

   APP_URL must exactly match the final HTTPS URL. An incorrect value breaks internal links and uploads.

3. 03

   Start the stack and check logs

   docker compose up -d
   docker compose logs -f bookstack

   On first startup, BookStack automatically runs the Laravel migrations to create the database schema. Wait for the line Server running on http://0.0.0.0:80 before continuing — this takes 30 to 60 seconds.

4. 04

   Configure reverse proxy and SSL

   With Caddy (automatic certificate management):

   wiki.yourdomain.com {
       reverse_proxy localhost:6875
   }

   Reload Caddy: systemctl reload caddy.

   With Nginx + Certbot:

   server {
       listen 80;
       server_name wiki.yourdomain.com;
       return 301 https://$host$request_uri;
   }
   server {
       listen 443 ssl;
       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;
       location / {
           proxy_pass http://127.0.0.1:6875;
           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;
       }
   }

   Obtain the certificate with certbot --nginx -d wiki.yourdomain.com.

5. 05

   First login and securing the admin account

   Open https://wiki.yourdomain.com. The default account is [email protected] with the password password. Change them immediately under Settings → Profile.

   Then verify that SMTP works: Settings → Email configuration → Send a test email. If the test fails, check the logs: docker compose logs bookstack | grep -i mail.

Advanced configuration: SSO, LDAP and SAML

Backing up and restoring BookStack

#!/bin/bash
BACKUP_DIR=/var/backups/bookstack
mkdir -p $BACKUP_DIR
DATE=$(date +%Y%m%d)
docker exec $(docker ps -qf name=mariadb) \
  mysqldump -u bookstack -pchangeme_bk bookstack \
  > $BACKUP_DIR/bookstack-db-$DATE.sql
tar -czf $BACKUP_DIR/bookstack-uploads-$DATE.tar.gz /opt/bookstack/data/bookstack/uploads
find $BACKUP_DIR -mtime +14 -delete

Troubleshooting: common errors

Frequent issues and solutions

• SMTP error 'Connection refused' or timeout: check that MAIL_PORT matches the actual port (587 for STARTTLS, 465 for SSL). Some SMTP servers block outgoing port 25. Test connectivity from the container: docker exec -it bookstack curl -v telnet://smtp.yourdomain.com:587.
• Permissions on storage/: 500 error or blank page: the /opt/bookstack/data/bookstack folder must be owned by UID 1000 (the PUID variable). Fix with chown -R 1000:1000 /opt/bookstack/data/bookstack then restart the container.
• Slowness or MariaDB timeout at startup: BookStack waits for MariaDB to be ready. If the BookStack container restarts in a loop during the first seconds, that is normal. Add a healthcheck to the mariadb service in the Compose file or wait 30 seconds before inspecting logs.
• Images not displaying after a domain change: APP_URL must exactly match the public HTTPS URL. If you change domains, update APP_URL in the Compose file, restart the container, then run php artisan bookstack:update-url from inside the container to update the URLs stored in the database.
• Migrations hang on first startup (OOM): if the VPS has less than 2 GB of RAM, Laravel migrations can be killed by the OOM killer. Add a 2 GB swap file (fallocate -l 2G /swapfile && mkswap /swapfile && swapon /swapfile) or increase the VPS RAM before retrying.

Updating BookStack

cd /opt/bookstack
docker compose pull
docker compose up -d
docker compose logs -f bookstack

Further reading

• Host Nextcloud on a VPS — cloud storage and document collaboration.
• Host Gitea on a VPS — self-hosted Git forge for your development teams.
• Authentik on a VPS — open source SSO to centralize authentication for BookStack and your other apps.