Self-hosting BookStack on a VPS: Docker Compose, APP_URL, and the login you must change firstBookStack selbst hosten auf einem VPS: Docker Compose, APP_URL und der Login, den du zuerst ändern musst

The image: linuxserver.io, not solidnerdDas Image: linuxserver.io, nicht solidnerd

There are two commonly used BookStack Docker images with different environment variable conventions, and mixing their variable names is the single most common way to end up with a container that starts and does nothing useful. This guide uses lscr.io/linuxserver/bookstack, the linuxserver.io build, because its variables are the ones documented below and worth memorizing: APP_URL, APP_KEY, DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_DATABASE, plus the linuxserver-standard PUID, PGID and TZ for file ownership and logging. The other option, solidnerd/bookstack, uses a different variable set entirely (DB_HOST overlaps, but several others don't) — if you go looking at BookStack tutorials online and copy environment lines from two different ones, check which image each one assumes first.Es gibt zwei gebräuchliche BookStack-Docker-Images mit unterschiedlichen Konventionen für Umgebungsvariablen, und ihre Variablennamen zu vermischen ist der mit Abstand häufigste Weg, mit einem Container zu enden, der startet und nichts Sinnvolles tut. Diese Anleitung verwendet lscr.io/linuxserver/bookstack, den Build von linuxserver.io, weil seine Variablen diejenigen sind, die unten dokumentiert werden und sich zu merken lohnen: APP_URL, APP_KEY, DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_DATABASE, dazu die linuxserver-typischen PUID, PGID und TZ für Dateibesitz und Logging. Die andere Option, solidnerd/bookstack, verwendet einen komplett anderen Variablensatz (DB_HOST überschneidet sich, aber mehrere andere nicht) – suchst du online nach BookStack-Tutorials und kopierst Umgebungszeilen aus zwei verschiedenen, prüfe zuerst, von welchem Image jedes ausgeht.

The compose fileDie Compose-Datei

Two services: BookStack and MariaDB, both pinned so an upgrade is a line you change on purpose.Zwei Services: BookStack und MariaDB, beide gepinnt, damit ein Upgrade eine Zeile ist, die du bewusst änderst.

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:version-v25.02  # check hub.docker.com/r/linuxserver/bookstack/tags for the current release
    restart: unless-stopped
    depends_on:
      - bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - APP_URL=https://wiki.example.com
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USER=bookstack
      - DB_PASS=${DB_PASSWORD}
      - DB_DATABASE=bookstackapp
      - APP_KEY=${APP_KEY}
    volumes:
      - bookstack_config:/config
    ports:
      - "127.0.0.1:6875:80"

  bookstack_db:
    image: mariadb:11  # check hub.docker.com/_/mariadb/tags for the current point release
    restart: unless-stopped
    environment:
      - MARIADB_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
      - MARIADB_DATABASE=bookstackapp
      - MARIADB_USER=bookstack
      - MARIADB_PASSWORD=${DB_PASSWORD}
    volumes:
      - bookstack_db_data:/var/lib/mysql

volumes:
  bookstack_config:
  bookstack_db_data:

The web port is bound to 127.0.0.1 on purpose, so only the reverse proxy on the same host can reach it — nothing else in this stack needs to be reachable from outside the machine.Der Web-Port ist absichtlich an 127.0.0.1 gebunden, sodass ihn nur der Reverse-Proxy auf demselben Host erreicht – sonst muss in diesem Stack nichts von außerhalb der Maschine erreichbar sein.

APP_URL: get this wrong and every link breaksAPP_URL: falsch gesetzt, und jeder Link ist kaputt

APP_URL is not cosmetic. BookStack uses it to build every absolute link it emits — page URLs in search results, image and attachment links, the links in invite and password-reset e-mails, even the links inside its own navigation. Set it to http://localhost or leave it as whatever the image ships by default, and pages still load over HTTPS through Caddy, but every generated link points at the wrong scheme or host, so clicking almost anything inside BookStack sends you somewhere broken.APP_URL ist nicht kosmetisch. BookStack nutzt sie, um jeden absoluten Link zu bauen, den es ausgibt – Seiten-URLs in Suchergebnissen, Bild- und Anhang-Links, die Links in Einladungs- und Passwort-Reset-E-Mails, sogar die Links in der eigenen Navigation. Setzt du sie auf http://localhost oder lässt sie beim Standardwert des Images, laden Seiten zwar weiterhin über HTTPS durch Caddy, aber jeder generierte Link zeigt auf das falsche Schema oder den falschen Host, sodass ein Klick auf fast alles innerhalb von BookStack dich auf eine kaputte Seite schickt.

The value has to be the exact public address people will actually type, protocol included: https://wiki.example.com, not wiki.example.com and not http://. Set it before the first run if you can — BookStack writes some of this into its own generated content early, and changing APP_URL later is a matter of updating the environment variable and restarting, but anything already baked into e-mails that already went out won't retroactively fix itself.Der Wert muss genau die öffentliche Adresse sein, die Leute tatsächlich eintippen, inklusive Protokoll: https://wiki.example.com, nicht wiki.example.com und nicht http://. Setze sie nach Möglichkeit vor dem ersten Start – BookStack schreibt einiges davon früh in seine eigenen generierten Inhalte, und APP_URL später zu ändern heißt nur: Umgebungsvariable aktualisieren und neu starten, aber alles, was bereits in schon verschickte E-Mails eingebacken ist, repariert sich nicht rückwirkend von selbst.

The .env file: credentials and APP_KEYDie .env-Datei: Zugangsdaten und APP_KEY

Keep every secret out of the compose file itself:Halte jedes Secret aus der Compose-Datei selbst heraus:

printf 'DB_ROOT_PASSWORD=%s\nDB_PASSWORD=%s\n' "$(openssl rand -hex 24)" "$(openssl rand -hex 24)" > .env
chmod 600 .env

APP_KEY is the one variable worth being careful with. It's Laravel's application encryption key — BookStack is built on Laravel — and it protects sessions and any encrypted values BookStack stores. The linuxserver image expects you to supply it and documents one command to generate a valid key, using the same image and its appkey helper; run it once before the first start and put the printed value into your .env file:APP_KEY ist die eine Variable, bei der sich Sorgfalt lohnt. Es ist Laravels Anwendungs-Verschlüsselungsschlüssel – BookStack baut auf Laravel auf –, und er schützt Sessions und alle verschlüsselten Werte, die BookStack speichert. Das linuxserver-Image erwartet, dass du ihn mitlieferst, und dokumentiert einen Befehl, der mit demselben Image und seinem appkey-Helfer einen gültigen Schlüssel erzeugt; führe ihn einmal vor dem ersten Start aus und trage den ausgegebenen Wert in deine .env-Datei ein:

docker run --rm -it --entrypoint /bin/bash lscr.io/linuxserver/bookstack:version-v25.02 appkey

Copy the full base64:… output into .env as APP_KEY=<value> (no quotes) so it is pinned and backed up with the rest of your secrets rather than living only inside a container. If the container logs complain about a missing or invalid key on start, this variable is the first thing to check. Do not regenerate APP_KEY on a running instance with existing data — it invalidates active sessions and any data BookStack encrypted with the old key.Kopiere die vollständige base64:…-Ausgabe als APP_KEY=<Wert> (ohne Anführungszeichen) in die .env, damit der Schlüssel gepinnt und zusammen mit deinen anderen Secrets gesichert ist, statt nur in einem Container zu leben. Beschweren sich die Container-Logs beim Start über einen fehlenden oder ungültigen Schlüssel, ist diese Variable das Erste, was du prüfst. Generiere APP_KEY nicht auf einer laufenden Instanz mit bestehenden Daten neu – das macht aktive Sessions und alle Daten ungültig, die BookStack mit dem alten Schlüssel verschlüsselt hat.

The default admin login, and changing it immediatelyDer Standard-Admin-Login, und ihn sofort ändern

BookStack ships a default administrator account on first install: [email protected] with the password password. This is not a placeholder you're expected to notice and ignore — it's a real, working login, documented as the initial account, and it is the very first thing anyone scanning for exposed BookStack instances tries. The moment the container is reachable at all — even before Caddy and a real hostname are in front of it — log in with that account and immediately change the e-mail and password — avatar/username top-right → Edit Profile — or, as admin, replace it via Settings → Users. Treat "container is up" and "default login is still valid" as the same window of exposure, because it is.BookStack bringt bei der Erstinstallation ein Standard-Administratorkonto mit: [email protected] mit dem Passwort password. Das ist kein Platzhalter, den du bemerken und ignorieren sollst – es ist ein echter, funktionierender Login, als Initialkonto dokumentiert, und er ist das Allererste, was jeder ausprobiert, der nach offen erreichbaren BookStack-Instanzen scannt. In dem Moment, in dem der Container überhaupt erreichbar ist – noch bevor Caddy und ein echter Hostname davor stehen –, melde dich mit diesem Konto an und ändere sofort E-Mail und Passwort – Avatar/Benutzername oben rechts → Profil bearbeiten – oder ersetze es als Admin über Einstellungen → Benutzer. Behandle „Container läuft“ und „Standard-Login ist noch gültig“ als dasselbe Zeitfenster der Angreifbarkeit, denn genau das ist es.

HTTPS with CaddyHTTPS mit Caddy

wiki.example.com {
    reverse_proxy 127.0.0.1:6875
}

That's the whole file. Caddy requests and renews the certificate automatically as soon as it starts, provided the A record already resolves to the machine — point DNS first, let it settle, then start Caddy. This is also exactly why APP_URL has to match: Caddy is terminating TLS and proxying to plain HTTP internally, and BookStack has no way to know the outside world sees HTTPS unless APP_URL says so.Das ist die ganze Datei. Caddy fordert das Zertifikat automatisch an und erneuert es, sobald es startet, vorausgesetzt der A-Eintrag zeigt bereits auf die Maschine – richte zuerst das DNS ein, lass es sich setzen, und starte dann erst Caddy. Das ist auch genau der Grund, warum APP_URL übereinstimmen muss: Caddy terminiert TLS und proxyt intern auf einfaches HTTP, und BookStack hat keine Möglichkeit zu wissen, dass die Außenwelt HTTPS sieht, wenn APP_URL es nicht sagt.

Read this before you buy: the NAT catch for 443Lies das, bevor du kaufst: die NAT-Falle bei Port 443

A NAT IPv4 VPS forwards a handful of ports to the machine; whether 443 is among them depends on the plan, so check before you point a domain at the box — and whichever ports you get belong to the machine, not to any one container. Run just BookStack on this VPS and it's a non-issue: Caddy binds 443, BookStack sits behind it, done. It only becomes a decision the moment you want a second HTTPS service on the same box — you cannot bind two things to port 443 at the network layer, so the fix is one Caddy instance as the only thing on 443, with a separate block per hostname routing to a different internal port. If you specifically need a standalone address with 443 to itself, that exists but is arranged by e-mail, not something you self-service from the panel. NAT IPv4 vs a dedicated IP and NAT IPv4, ports and forwarding cover the mechanics.Ein NAT-IPv4-VPS leitet eine Handvoll Ports auf die Maschine weiter; ob 443 dabei ist, hängt vom Tarif ab, also prüfe das, bevor du eine Domain auf die Box zeigen lässt – und welche Ports du auch bekommst, sie gehören der Maschine, nicht einem einzelnen Container. Läuft nur BookStack auf diesem VPS, ist das kein Thema: Caddy bindet 443, BookStack sitzt dahinter, fertig. Zur Entscheidung wird es erst in dem Moment, in dem du einen zweiten HTTPS-Dienst auf derselben Box willst – du kannst nicht zwei Dinge auf Netzwerkebene an Port 443 binden, also besteht die Lösung aus einer Caddy-Instanz als einzigem Ding auf 443, mit einem eigenen Block pro Hostname, der auf einen anderen internen Port routet. Brauchst du gezielt eine eigenständige Adresse mit 443 nur für dich, gibt es das, aber es wird per E-Mail geregelt, nicht als Self-Service im Panel. NAT IPv4 vs. dedizierte IP und NAT IPv4, Ports und Weiterleitung behandeln die Mechanik.

Where uploads and images actually liveWo Uploads und Bilder tatsächlich liegen

Everything BookStack writes lives under the single /config volume in the compose file above: the application's own config, its logs, and — depending on how BookStack is set to store attachments — page images and file uploads as well. That single volume is why the backup section below only needs to care about two things, not five: the database, and this one directory tree. There's nothing else on the container's filesystem worth preserving; a fresh container with the same .env and the same two volumes reconstructs the running instance exactly.Alles, was BookStack schreibt, liegt unter dem einen /config-Volume in der Compose-Datei oben: die eigene Konfiguration der Anwendung, ihre Logs und – je nachdem, wie BookStack zum Speichern von Anhängen eingestellt ist – auch Seitenbilder und Datei-Uploads. Genau dieses eine Volume ist der Grund, warum sich der Backup-Abschnitt unten nur um zwei Dinge kümmern muss, nicht um fünf: die Datenbank und diesen einen Verzeichnisbaum. Es gibt sonst nichts auf dem Dateisystem des Containers, das es zu erhalten lohnt; ein frischer Container mit derselben .env und denselben zwei Volumes rekonstruiert die laufende Instanz exakt.

BackupsBackups

Two pieces, because the database changes on every edit and the volume doesn't:Zwei Teile, weil sich die Datenbank bei jeder Bearbeitung ändert und das Volume nicht:

docker compose exec bookstack_db sh -c 'mariadb-dump -u root -p"$MARIADB_ROOT_PASSWORD" bookstackapp' > "bookstack-$(date +%F).sql"

That reads the root password straight out of the bookstack_db container's own environment, so it never touches your shell history. For the config and uploads volume:Das liest das Root-Passwort direkt aus der eigenen Umgebung des bookstack_db-Containers, sodass es nie deine Shell-History berührt. Für das Config- und Uploads-Volume:

docker run --rm -v bookstack_bookstack_config:/data -v "$(pwd)":/backup alpine:3.20 \
  tar czf "/backup/bookstack-config-$(date +%F).tar.gz" -C /data .

Check the actual volume name first with docker compose config --volumes — Compose prefixes it with the project directory name, so it may not match the example exactly. Copy both files off the VPS entirely; a dump sitting on the same disk as the instance it came from is a file, not a backup. back up your VPS covers what off-machine actually means in practice.Prüfe zuerst den tatsächlichen Volume-Namen mit docker compose config --volumes – Compose stellt ihm den Namen des Projektverzeichnisses voran, sodass er nicht exakt dem Beispiel entsprechen muss. Kopiere beide Dateien vollständig vom VPS herunter; ein Dump, der auf derselben Platte liegt wie die Instanz, von der er stammt, ist eine Datei, kein Backup. Backup deines VPS beschreibt, was das in der Praxis bedeutet.

UpdatesUpdates

docker compose pull
docker compose up -d

Take both backups immediately before you do this, not after. BookStack runs its own database migrations automatically the first time it starts on a new version — there's no separate migration command to remember — but that migration is a one-way trip on the data you just dumped. Read the release notes for the version you're jumping to before bumping the pinned tag, especially across a large version gap.Mach beide Backups unmittelbar davor, nicht danach. BookStack führt seine eigenen Datenbank-Migrationen automatisch beim ersten Start auf einer neuen Version aus – es gibt keinen separaten Migrationsbefehl zu merken –, aber diese Migration ist eine Einbahnstraße für die Daten, die du gerade gesichert hast. Lies die Release Notes zu der Version, auf die du springst, bevor du den gepinnten Tag hochsetzt, besonders bei einem großen Versionssprung.

SizingDimensionierung

PHP plus MariaDB idles low, and BookStack itself is a fairly small application — most of the CPU cost is rendering Markdown and search indexing, not anything constant. 1 GiB works for a personal wiki: you, maybe a couple of collaborators, moderate page counts, occasional images.PHP plus MariaDB laufen im Leerlauf mit wenig Last, und BookStack selbst ist eine recht kleine Anwendung – die meisten CPU-Kosten entstehen beim Rendern von Markdown und bei der Suchindizierung, nicht durch etwas Dauerhaftes. 1 GiB reicht für ein persönliches Wiki: du, vielleicht ein paar Mitarbeiter, moderate Seitenzahlen, gelegentliche Bilder.

2 GiB is comfortable for a small team with images — the point where MariaDB's buffer pool actually helps, PHP-FPM can hold a few more workers without swapping, and a steady stream of screenshots and diagrams being uploaded and thumbnailed doesn't compete with everything else on the box. Disk is mostly the image library rather than the application or database, so watch it the same way you'd watch any wiki that accumulates attachments over years, not months.2 GiB sind komfortabel für ein kleines Team mit Bildern – der Punkt, ab dem MariaDBs Buffer-Pool tatsächlich hilft, PHP-FPM ein paar Worker mehr halten kann, ohne zu swappen, und ein stetiger Strom aus Screenshots und Diagrammen, die hochgeladen und als Thumbnail erzeugt werden, nicht mit allem anderen auf der Box konkurriert. Speicherplatz ist größtenteils die Bild-Library statt der Anwendung oder Datenbank, also behalte ihn im Auge wie bei jedem Wiki, das über Jahre Anhänge ansammelt, nicht über Monate.

Optional: SMTP for invites and password resetsOptional: SMTP für Einladungen und Passwort-Resets

BookStack can send e-mail for user invitations and password resets, and without it configured, those flows simply don't work — there's no in-app fallback. If you want them, add the standard Laravel mail variables to the bookstack service's environment: MAIL_DRIVER=smtp, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_ENCRYPTION, and MAIL_FROM. Any normal SMTP relay works — a transactional mail provider, or your own mail server if you already run one. This is worth setting up before you invite anyone else, since "send them a manual reset link" is not a real substitute for the password-reset flow once more than one or two people use the wiki.BookStack kann E-Mails für Benutzereinladungen und Passwort-Resets versenden, und ohne diese Konfiguration funktionieren diese Abläufe schlicht nicht – es gibt keinen In-App-Fallback. Willst du sie, füge die Standard-Laravel-Mail-Variablen zur Umgebung des bookstack-Services hinzu: MAIL_DRIVER=smtp, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_ENCRYPTION und MAIL_FROM. Jedes normale SMTP-Relay funktioniert – ein transaktionaler Mail-Anbieter oder dein eigener Mailserver, falls du schon einen betreibst. Das lohnt sich einzurichten, bevor du jemand anderen einlädst, denn „schick ihm manuell einen Reset-Link“ ist kein echter Ersatz für den Passwort-Reset-Ablauf, sobald mehr als ein oder zwei Leute das Wiki nutzen.

On overnight.hostBei overnight.host

Full disclosure: this is what we sell. Basic (2 vCPU / 2 GiB / 50 GB) is comfortable for a small team's wiki with images; a personal wiki runs on less, and a much larger image library is a reason to move up for the disk, not the RAM.Zur vollen Transparenz: Das ist, was wir verkaufen. Basic (2 vCPU / 2 GiB / 50 GB) ist komfortabel für das Wiki eines kleinen Teams mit Bildern; ein persönliches Wiki läuft mit weniger, und eine deutlich größere Bild-Library ist ein Grund, wegen der Platte hochzustufen, nicht wegen des RAM.

Linux KVM VPS — EUR 4.99 to EUR 59.99 a month, on our own single-tenant bare metal in Dallas, TX and Charlotte, NC. Full hardware virtualisation (KVM), your own kernel, full root. Six tiers, vps-starter to vps-ultra. Starter is 1 vCPU, 1 GiB RAM, 25 GB disk.Linux-KVM-VPS — 4,99 bis 59,99 EUR im Monat, auf unserer eigenen Single-Tenant-Bare-Metal-Hardware in Dallas, TX und Charlotte, NC. Vollständige Hardware-Virtualisierung (KVM), eigener Kernel, volles Root. Sechs Tarife, vps-starter bis vps-ultra. Starter hat 1 vCPU, 1 GiB RAM, 25 GB Speicher.

You order in the shop, pay by card (Stripe) or SEPA bank transfer, and your login details are e-mailed to you once the service is set up. Support is e-mail, run by one person, with no guaranteed response time. All prices are final totals under the German small-business rule (§19 UStG); no VAT is added or shown.Du bestellst im Shop, zahlst per Karte (Stripe) oder SEPA-Überweisung, und deine Zugangsdaten werden dir per E-Mail zugeschickt, sobald der Dienst eingerichtet ist. Support läuft per E-Mail, von einer einzelnen Person betrieben, ohne garantierte Reaktionszeit. Alle Preise sind Endpreise. Gemäß § 19 UStG wird keine Umsatzsteuer ausgewiesen.

Order vps-basic → · Linux KVM VPS overviewvps-basic bestellen → · Übersicht Linux-KVM-VPS

Written by the person who runs overnight.host: a small, honest hosting company on dedicated bare metal — Linux VPS, game servers, web hosting. Live status at up.overnight.host.Geschrieben von der Person, die overnight.host betreibt: ein kleines, ehrliches Hosting-Unternehmen auf dedizierter Bare-Metal-Hardware — Linux-VPS, Gameserver, Webhosting. Live-Status unter up.overnight.host.