BookStack

Overview

BookStack is a self-hosted wiki for knowledge you want other people to find and maintain. Books contain chapters and pages; shelves group related books. It suits a household handbook, a small team’s documentation, or runbooks for a home server. Search, page revisions, attachments, and permissions help keep instructions usable as they grow.

Pages can use a visual editor or Markdown. The interface includes English and Russian, and readers use a browser on a desktop or phone; this recipe does not include native mobile or desktop apps. BookStack can replace the documentation side of Notion or Confluence, but it does not reproduce Notion databases, project boards, or all of Confluence’s integrations.

This recipe pins BookStack v26.09.2 in the community LinuxServer image, together with MariaDB 11.4.13. BookStack’s documentation links to third-party container options; the image is not published by the BookStack project. The app’s /config volume holds uploads, private attachments, configuration, and themes; the separate MariaDB volume holds accounts, page content, revisions, and settings. Both belong in a backup, together with the original APP_KEY.

BookStack is MIT-licensed; the recipe is MIT-licensed separately. OIDC, SAML, and TOTP two-factor authentication are native features, but this recipe starts with local email/password authentication and does not configure an identity provider. Login through a proxy’s user header is not part of this recipe.

The resource figures are planning estimates for a small installation: one CPU core, 1 GB RAM minimum, 2 GB recommended, and 5 GB disk before your documents and attachments. The images provide amd64 and arm64 variants; the runtime checks here cover amd64 only. A separate database and healthchecks are included, but monitoring and resource limits are not, so the reliable deployment level is partial.

Sources: BookStack documentation, installation options, LinuxServer image, authentication, and release v26.09.2.

Security assessment

The initial administrator credentials are public and must be replaced before network access. Keep the service behind HTTPS and the database private. Preserve the original APP_KEY with encrypted off-server copies of both data volumes: it protects encrypted application data, including MFA secrets. The recipe uses a third-party LinuxServer container. Image vulnerabilities have not been scanned here; functional smoke checks are not a security audit.

Step-by-step guide

Requirements and preparation

Use 64-bit Ubuntu 22.04+ or Debian 12+ with Docker Engine and Compose v2.24+. Budget at least one CPU core, 1 GB RAM (2 GB recommended), and 5 GB disk plus documents. Both images offer amd64 and arm64; this recipe was run on amd64.

mkdir -p ~/services/bookstack
cd ~/services/bookstack
# Copy the recipe files, including backup.sh, restore.sh, and proxy/ here.
cp .env.example .env
chmod 600 .env
# Generate APP_KEY; paste the whole base64:... value into .env.
printf 'base64:'; openssl rand -base64 32
# Run twice for independent database passwords.
openssl rand -hex 32
openssl rand -hex 32

Edit .env before starting. All parameters:

Do not reuse placeholder secrets or change database passwords in .env after initialization without rotating the corresponding database users. The backup scripts source the local .env as trusted shell configuration: keep it private and use simple generated values.

Start and replace the initial account

docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 600
curl --fail http://127.0.0.1:6875/status
# Set your own email, name, and unique password. --initial replaces the public default account.
docker compose exec bookstack php /app/www/artisan bookstack:create-admin \
  --initial --email=you@example.com --name='Your name' --generate-password

Save the generated password securely. The upstream initial credentials are admin@admin.com / password: replace this account before providing network access. Open the exact BOOKSTACK_APP_URL and sign in with your new credentials. Change interface language under your account profile; enable MFA in account authentication settings. Do not enable public access or open registration unless you intend to share the content.

VPS

Keep port 6875 on loopback and the database unexposed. Set BOOKSTACK_APP_URL=https://docs.example.com, point DNS to the host, configure HTTPS, and allow only SSH/HTTP/HTTPS through the firewall. Replace the default account before enabling the public proxy. Maintain encrypted off-server backups. SMTP and external authentication require additional settings from the upstream documentation.

Trusted local network

For one person use ssh -L 6875:127.0.0.1:6875 user@server and open http://localhost:6875 with the matching BOOKSTACK_APP_URL. For shared LAN access use an HTTPS proxy, or bind the published port to one private address and restrict it with a firewall. The browser must use the configured URL; changing only the published port is insufficient.

Domain and HTTPS

Use one example from proxy/: Caddy manages certificates, Nginx expects existing certificate files, and Traefik expects a websecure entry point and letsencrypt resolver. These examples run on the host and reach 127.0.0.1:6875; a containerized proxy needs a shared Docker network and the app’s internal port 80 instead. Nginx permits 50 MB requests; PHP’s upload limit must also permit the file size you need.

Set the exact external HTTPS URL in .env before first start. When changing an existing URL, first back up, change BOOKSTACK_APP_URL, recreate the app, then update stored links:

docker compose up -d --wait --wait-timeout 600
docker compose exec bookstack php /app/www/artisan bookstack:update-url \
  http://localhost:6875 https://docs.example.com

Backup

./backup.sh

The script stops BookStack writers, dumps MariaDB, and archives /config, .env, and compose.yaml into one private backups/bookstack-<timestamp>.tar. MariaDB stays running. An app that was running is restarted even if the backup fails. Encrypt the archive and copy it off-server: it contains documents, attachments, database credentials, and APP_KEY. A database dump alone cannot restore uploaded files; a /config archive alone cannot restore pages.

Restore

Restore replaces the database and all /config data. Use only your own trusted archives. Start the matching recipe with the original APP_KEY and compatible application/database versions. Compare the archived configuration.env with .env manually; the script never sources or activates the archived file. On a fresh host, create the containers and wait for MariaDB before restoring.

docker compose up -d --wait --wait-timeout 600
./restore.sh ./backups/bookstack-TIMESTAMP.tar
curl --fail http://127.0.0.1:6875/status
docker compose logs --tail=100 bookstack

The script validates required archive members and makes a safety backup before replacing data. If replacement fails, keep the app stopped and repair or restore again. Check both a saved page and an attachment after restoring. The smoke test checks database and file restoration on amd64.

Update

Read release notes, run ./backup.sh, and copy the archive off-server. Change BOOKSTACK_VERSION to an exact reviewed release, then:

docker compose pull
docker compose up -d --wait --wait-timeout 600
docker compose logs --tail=100 bookstack

Do not use latest. Startup applies database migrations. MariaDB has its own pinned version in Compose; review its upgrade procedure separately before changing it.

Rollback

Never run an older BookStack against a database migrated by a newer version. Keep MariaDB running, stop the app, set BOOKSTACK_VERSION and APP_KEY to the values from before the upgrade, and recreate the app container without starting it:

docker compose stop bookstack
# Edit .env now: previous exact application version and original APP_KEY.
docker compose pull bookstack
docker compose create bookstack
./restore.sh ./backups/bookstack-BEFORE-UPDATE.tar
curl --fail http://127.0.0.1:6875/status

The stopped container lets the safety backup run without launching the old application on the new database. Do not downgrade MariaDB’s physical data directory; if its version changed, restore the SQL dump into a clean compatible database volume, preserving the existing volume until recovery is verified.

Stop and remove

docker compose down stops and removes containers while retaining both data volumes. After verifying an off-server backup, docker compose down --volumes permanently deletes the database, documents, uploads, accounts, and configuration. Removing the recipe directory additionally deletes local backups; preserve the archive elsewhere first.

Sources: installation, LinuxServer image and configuration, backup and restore, security, and system CLI.

Report a recipe problem

Tell us how it went on your server

Opens a prefilled GitHub issue. A GitHub account is required; submitting the issue makes it public.

Troubleshooting

Inspect startup and database health

docker compose ps
docker compose logs --tail=150 database bookstack
curl --fail http://127.0.0.1:6875/status

First startup initializes MariaDB and runs migrations. /status should return HTTP 200 with database, cache, and session all true. For a database error, verify the two database passwords and the database healthcheck. Editing initialization passwords in .env does not rotate an existing MariaDB user’s password. Never delete a populated volume to fix a credential error.

Missing or invalid APP_KEY

Generate one key with printf 'base64:'; openssl rand -base64 32 before first start. An initialized instance needs its original key. Restore it from the protected backup instead of generating a replacement, especially when MFA is enabled.

Login, links, or assets use the wrong address

Match BOOKSTACK_APP_URL exactly to the browser address, including HTTPS and port. Follow the URL-change procedure in installation.md, including bookstack:update-url, for an existing installation. Clear browser cookies after changing origin. Forward Host and X-Forwarded-Proto from the trusted HTTPS proxy and keep direct untrusted access blocked.

Cannot sign in

The public initial account must be replaced. The documented bookstack:create-admin --initial command is for initial setup, not a general password reset. Use the upstream recovery procedure or configured email recovery for an existing account. Diagnose mail errors before relying on password-reset email; this recipe does not configure SMTP.

Uploads fail or disk fills

Check docker system df and free disk space on the Docker host. /config and the database volume both grow; documents and attachments need room in addition to image layers. Check the reverse proxy request limit and LinuxServer/PHP upload settings together. For permissions, confirm PUID and PGID match the intended file owner; do not make private files world-writable.

Backup or restore fails

Check database logs, free disk, and archive permissions. Restore accepts only the four required members produced by backup.sh; use a complete trusted archive, not a standalone SQL or config file. Keep the original archive untouched and compare archived configuration.env with active .env without publishing secrets. If replacement has started and fails, keep BookStack stopped until recovery is complete. Do not downgrade MariaDB’s physical data directory.

Sources: BookStack troubleshooting, backup/restore, system CLI, and LinuxServer image.