How to Deploy BookStack on a VPS

#Install BookStack (Docker Compose)

BookStack doesn't publish its own Docker image; its installation docs list community images instead. This guide uses the linuxserver.io one, lscr.io/linuxserver/bookstack (the same image as the catalog snippet), paired with linuxserver's MariaDB image. Create a project directory:

copymkdir -p ~/bookstack && cd ~/bookstack

BookStack needs an application key (APP_KEY) — Laravel uses it to encrypt sessions and stored secrets. The image ships a helper that prints a fresh one. Generate it, plus two database passwords, into a .env file that Compose reads automatically. The [ -f .env ] guard keeps the step safe to re-run: changing the key or passwords on an existing install would lock you out of your own data.

copyif [ ! -f .env ]; then
  APP_KEY=$(docker run --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey | tail -n 1)
  cat > .env <<EOF
APP_URL=https://docs.example.com
APP_KEY=$APP_KEY
DB_PASS=$(openssl rand -hex 16)
DB_ROOT_PASS=$(openssl rand -hex 16)
EOF
  chmod 600 .env
fi
grep -c '^APP_KEY=base64:' .env

The last line should print 1 — a key that starts with base64:. Set APP_URL to the address people will actually use: BookStack builds every link and redirect from it, so a wrong value shows up as redirects to the wrong host.

Now the compose file. Both services use bind-mounted folders next to the file, which keeps backups a matter of copying one directory:

copycat > docker-compose.yml <<'YAML'
services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    restart: unless-stopped
    depends_on: [db]
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - APP_URL=${APP_URL}
      - APP_KEY=${APP_KEY}
      - DB_HOST=db
      - DB_PORT=3306
      - DB_USERNAME=bookstack
      - DB_PASSWORD=${DB_PASS}
      - DB_DATABASE=bookstack
    volumes:
      - ./bookstack_app_data:/config
    ports:
      # Loopback only: Caddy is the only way in from outside.
      - "127.0.0.1:6875:80"

  db:
    image: lscr.io/linuxserver/mariadb:latest
    container_name: bookstack-db
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASS}
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=${DB_PASS}
    volumes:
      - ./bookstack_db_data:/config
YAML

Start it and wait for BookStack to answer. The first boot runs the database migrations, so give it a minute:

copydocker compose up -d
for i in $(seq 1 60); do
  code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:6875/login)
  [ "$code" = "200" ] && break
  sleep 5
done
echo "BookStack answered HTTP $code"
docker compose ps

HTTP 200 on /login and both containers running means the install worked. If it never answers, jump to Troubleshooting.

#HTTPS + domain

Point an A record for your wiki hostname (say docs.example.com) at the server's public IP and wait for it to resolve. Then put TLS in front of 127.0.0.1:6875 — the simplest route is Automatic HTTPS with Caddy:

docs.example.com {
    reverse_proxy 127.0.0.1:6875
}

Caddy fetches and renews the certificate on its own. If you run Caddy as a container, 127.0.0.1 is the container's own loopback — put Caddy in the same compose file and use reverse_proxy bookstack:80, dropping the host port publish.

Make sure APP_URL in .env matches the HTTPS address exactly, then apply it:

copycd ~/bookstack && docker compose up -d

#First login and hardening

Open https://docs.example.com. The linuxserver image seeds a default administrator: admin@admin.com / password. That is public knowledge, so the first thing you do is sign in and change both the email and the password under My Account.

Then, in Settings:

• Registration is off by default. Leave it off and invite people, or turn it on only with a restricted email domain.
• Roles and permissions are where BookStack earns its keep. Create roles (Editor, Viewer) rather than handing out Admin, and use book-level permissions for anything sensitive.
• Multi-factor authentication can be enforced per role. Enforce it for Admin at minimum.
• For a team with an identity provider, BookStack supports SAML 2.0, OIDC and LDAP through environment variables — see the BookStack docs for the exact keys before you add them to the compose file.

Email is needed for invites and password resets. Add the MAIL_* variables from the BookStack docs to the bookstack service when you're ready.

#Backups

Two things make up a BookStack install: the database and the files (uploads, images, themes and the .env with your APP_KEY). Lose the key and encrypted data in the database can't be read, so back up both together.

A consistent database dump, taken as the bookstack database user with the password the container already holds (the single quotes make the variables expand inside the container, not on the host). The test -s fails the step if the dump came out empty, which is how a wrong password usually shows up:

copycd ~/bookstack
docker compose exec -T db sh -c 'mariadb-dump -u "$MYSQL_USER" -p"$MYSQL_PASSWORD" bookstack' > bookstack-db-$(date +%F).sql
test -s bookstack-db-$(date +%F).sql && ls -lh bookstack-db-*.sql

Then archive the app's config directory and the .env:

copycd ~/bookstack
sudo tar czf bookstack-files-$(date +%F).tar.gz bookstack_app_data .env docker-compose.yml
ls -lh bookstack-files-*.tar.gz

Copy both files off the server — object storage, another machine, anywhere that survives this VPS dying. To restore, recreate the directory with the archive, start only the database (docker compose up -d db), pipe the SQL back in with mariadb, then start everything. Do that once on a scratch box so you know it works.

#Upgrades

copycd ~/bookstack
docker compose pull
docker compose up -d

The container runs any new database migrations on start. Take the backup above first, and read the BookStack release notes before a large jump — some releases note changes to themes or the permission system that are worth checking.

#Troubleshooting

The page redirects to the wrong address, or loads without styling. APP_URL doesn't match the URL in your browser. Fix it in .env, then docker compose up -d.

BookStack never answers on 6875. Read docker compose logs bookstack. The usual causes are the database still initializing on first boot (wait a minute) or a password mismatch between DB_PASSWORD and MYSQL_PASSWORD — both come from DB_PASS, so check you didn't edit one by hand.

"The MAC is invalid" or sessions breaking after a move. The APP_KEY changed. Restore the original .env from your backup; the key must stay the same for the life of the install.

Uploads fail on large files. Caddy doesn't cap body size by default; the limit is PHP's. Raise upload_max_filesize and post_max_size in the PHP config under bookstack_app_data/php/, then restart the container.

#Verification + next steps

You're done when https://docs.example.com loads with a valid certificate, the default admin@admin.com login no longer works, a second user can sign in with the role you gave them, and you have a database dump and a file archive stored off the box.

From there: set up email so invites work, connect your identity provider if you have one, and schedule the two backup commands with cron. Comparing options first? Wiki.js vs BookStack covers the other common choice, and the Wiki.js guide walks through that install. For host picks, see Best VPS for Self-Hosting.