BookStack auf einem Managed VPS hosten: Ihre Dokumentation bei Ihnen

Was BookStack kann

BookStack ist eine Dokumentationsplattform, die einfach bleiben soll: Sein README zielt auf einen sofortigen Einstieg, mit einfachen Kenntnissen aus der Textverarbeitung. Ihre Teams schreiben dort ihre Verfahren, ihre Dokumentation und ihre Wissensdatenbank, in einem Browser, auf Wunsch auf Deutsch.

• Vier Ordnungsebenen: Regale fassen Bücher zusammen, Bücher tragen Kapitel und Seiten, die Kapitel sind optional, und der Inhalt lebt in den Seiten.
• Zwei Editoren: ein visueller Editor als Standard und ein Markdown-Editor mit Live-Vorschau, dazu kommen die Diagramme von diagrams.net.
• Die Suche: in einem Buch oder über alle Bücher, Kapitel und Seiten.
• Die Rechte: Rollen für das ganze System und Berechtigungen, die einem Regal, einem Buch, einem Kapitel oder einer Seite eigen sind.
• Die Anmeldungen: E-Mail und Passwort, OpenID Connect, SAML 2.0, LDAP, mit einer Zwei-Faktor-Authentifizierung per App oder Backup-Codes, die sich pro Rolle erzwingen lässt.
• Nachverfolgung und Austausch: der Revisionsverlauf jeder Seite, eine REST-API und der Export als HTML, PDF, Text, Markdown oder portables ZIP.

Das Projekt steht zu seinen Entscheidungen: Sein README stellt klar, dass BookStack nicht als erweiterbare Plattform für andere Einsatzzwecke gedacht ist, und es bleibt bei der Dokumentation. Sein PDF-Rendering läuft über dompdf, ohne zusätzliche Installation, mit begrenzten Fähigkeiten; das Projekt dokumentiert andere Engines mit EXPORT_PDF_COMMAND.

Was die MIT-Lizenz erlaubt

BookStack wird von Dan Brown und den Mitwirkenden des Projekts unter der MIT-Lizenz veröffentlicht. Sie erlaubt jede Nutzung, jede Änderung und jede Weitergabe, unter einer Bedingung: der Copyright-Hinweis und der Lizenztext bleiben in jeder Kopie der Software erhalten. Die FAQ des Projekts stellt klar, dass sich diese Namensnennung auf den Code bezieht, den Sie weitergeben: Nichts verpflichtet Sie, den Namen oder das Logo von BookStack auf Ihrer Instanz anzuzeigen.

Das Projekt führt nur eine einzige, freie und kostenlose Version: Es bietet keine Enterprise-Edition an, und es hat kein offizielles Hosting und plant auch keines. Es verkauft dagegen Support-Pakete, die zusammen mit Spenden und Sponsoring zu seiner Finanzierung beitragen. BookStack wird also auf Ihrem Server installiert, ohne eine Lizenz zu kaufen.

Die Voraussetzungen von BookStack

Docker bleibt optional. Das Projekt veröffentlicht kein offizielles Image: Die Installationen im Container stammen aus Community-Projekten, LinuxServer.io und solidnerd. Dieser Leitfaden folgt dem offiziellen Weg, PHP und MySQL direkt auf dem Server, der nichts weiter verlangt.

Die Dokumentation schließt PHP-Shared-Hosting aus: BookStack verlangt einen Server, den Sie selbst administrieren. Sie beziffert weder den nötigen Arbeitsspeicher noch den Prozessor. Auf einem Managed VPS beschreiben Sie uns Ihren Einsatz, die Zahl der Personen und das Volumen an Bildern und Anhängen, und wir empfehlen Ihnen die passende Größe.

Die Installation von BookStack

Das Projekt bietet zwei Wege: ein Skript für Ubuntu, das kürzeste auf einem neuen Server, und eine manuelle Installation für alle anderen Fälle.

Mit dem Skript des Projekts, auf einem frischen Ubuntu

wget https://codeberg.org/bookstack/devops/raw/branch/main/scripts/installation-ubuntu-24.04.sh
chmod a+x installation-ubuntu-24.04.sh
sudo ./installation-ubuntu-24.04.sh

Diese Skripte sind einem frisch installierten System vorbehalten: Sie können eine bestehende Webkonfiguration überschreiben. Sie lassen außerdem zwei Themen aus, die E-Mail-Einstellungen und die Sicherheit des Systems, die separat einzuplanen sind.

Das Skript legt BookStack in /var/www/bookstack ab. Das von Ubuntu 26.04 fragt nach der Domain und der Adresse des Administratorkontos und zeigt am Ende ein zufällig erzeugtes Passwort an, das in seinem Protokoll fehlt: Notieren Sie es. Notieren Sie bei einem anderen Skript die am Ende angezeigten Zugangsdaten und ändern Sie jeden Standardzugang gleich bei der ersten Anmeldung.

Von Hand, auf jeder anderen Maschine

Beginnen Sie mit der Datenbank: eine Datenbank und ein auf diese Datenbank beschränkter Benutzer. Das Skript des Projekts geht so vor, mit einem Passwort Ihrer Wahl anstelle von change-me:

sudo mysql -u root --execute="CREATE DATABASE bookstack;"
sudo mysql -u root --execute="CREATE USER 'bookstack'@'localhost' IDENTIFIED BY 'change-me';"
sudo mysql -u root --execute="GRANT ALL ON bookstack.* TO 'bookstack'@'localhost';FLUSH PRIVILEGES;"

Holen Sie dann den Zweig release, setzen Sie die Rechte, die die Dokumentation für /var/www/bookstack nennt, und installieren Sie die Abhängigkeiten:

cd /var/www
sudo git clone https://source.bookstackapp.com/bookstack.git --branch release --single-branch bookstack
sudo chown -R $USER:www-data /var/www/bookstack
sudo chmod -R 755 /var/www/bookstack
sudo chmod -R 775 /var/www/bookstack/storage /var/www/bookstack/bootstrap/cache /var/www/bookstack/public/uploads
cd bookstack
composer install --no-dev
cp .env.example .env
sudo chmod 640 .env

Tragen Sie die Datenbank und die Adresse in .env ein:

APP_URL=https://docs.example.com
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=change-me

php artisan key:generate
php artisan migrate

Lassen Sie zum Schluss das Web-Root auf den Ordner public zeigen: DocumentRoot bei Apache, root bei Nginx. Ohne Apache oder wenn die Dateien .htaccess deaktiviert sind, ergänzen Sie die Regeln zur Umschreibung von Adressen: Das Projekt veröffentlicht Beispiele für Apache und für Nginx.

Eine manuelle Installation öffnet sich mit dem Konto admin@admin.com und dem Passwort password. Ändern Sie die Adresse und das Passwort gleich bei der ersten Anmeldung.

HTTPS und APP_URL

Die Besucher kommen über die Ports 80 und 443 an, unter dem Domainnamen des Servers. Legen Sie für diesen Namen A- und AAAA-Einträge an und fordern Sie dann das Zertifikat an: Das Skript für Ubuntu 26.04 konfiguriert Apache nur auf Port 80, und die Installationsseite überlässt HTTPS Ihnen. Certbot richtet das Zertifikat von Let’s Encrypt ein, passt Apache an und erneuert das Zertifikat selbstständig. Ersetzen Sie unter Nginx --apache durch --nginx.

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot
sudo certbot --apache -d docs.example.com

Stellen Sie danach die Adresse in .env auf HTTPS um. APP_URL muss genau der Adresse entsprechen, unter der man die Website besucht, Präfix eingeschlossen: Eine Abweichung zeigt sich an fehlenden Stilen, übergroßen Symbolen und kaputten Menüs. Eine Adresse mit https aktiviert die sicheren Cookies von selbst.

APP_URL=https://docs.example.com

Wenn schon Seiten existieren, behalten ihre Links in der Datenbank die alte Adresse. Sichern Sie die Datenbank und führen Sie dann den Befehl des Projekts aus:

php artisan bookstack:update-url http://docs.example.com https://docs.example.com

BookStack wird im Stammverzeichnis einer Domain oder Subdomain ausgeliefert, und die Dokumentation beschreibt auch eine Installation in einem Unterordner, etwa example.com/bookstack. Wenn ein Reverse Proxy vor Apache kommt, deklarieren Sie seine Adresse in APP_PROXIES: Ohne sie sehen das Audit-Protokoll und die Ratenbegrenzung die Adresse des Proxys anstelle der der Besucher. Die Dokumentation reserviert APP_PROXIES="*" für die Diagnose.

Wo Ihre Daten liegen

Behalten Sie dauerhaft denselben APP_KEY und sichern Sie ihn. BookStack nutzt ihn unter anderem, um die Secrets der Zwei-Faktor-Authentifizierung zu verschlüsseln: Ihn zu ändern kann diese Funktionen brechen, und seit der Version 26.09 gibt die Anwendung einen Fehler zurück, wenn er fehlt.

Bilder sind standardmäßig öffentlich

Bei der Standardspeicherung liefert der Webserver die Bilder direkt aus, was schnell geht, und jede Person, die ihre Adresse kennt, kann sie öffnen. Für eine interne Dokumentation treffen Sie die Wahl in STORAGE_TYPE:

Für große Dateien müssen drei Einstellungen zusammenpassen: FILE_UPLOAD_SIZE_LIMIT in .env, post_max_size und upload_max_filesize in php.ini sowie client_max_body_size unter Nginx, das standardmäßig 1 MB beträgt.

Zwei Einstellungen zählen auch für eine lebendige Dokumentation: Jede Seite behält standardmäßig 100 Revisionen (REVISION_LIMIT), und der Papierkorb bewahrt gelöschte Elemente 30 Tage auf (RECYCLE_BIN_LIFETIME).

Die E-Mails: SMTP und Warteschlange

BookStack sendet E-Mails für die Bestätigung der Adressen, vergessene Passwörter, Einladungen und Benachrichtigungen. Von einem Simafri-VPS aus läuft der Versand über ein authentifiziertes SMTP-Relay auf Port 587: die Adresse eines Postfachs, das Sie bereits haben, oder Simafri Suite.

MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=bookstack@example.com
MAIL_PASSWORD=change-me
MAIL_FROM=bookstack@example.com
MAIL_FROM_NAME=BookStack

Prüfen Sie das Ergebnis unter „Settings“, „Maintenance“ mit der Aktion „Send a Test Email“, die die aufgetretenen Fehler anzeigt. Ein Fehlschlag bei einer Einladung erscheint auf dem Bildschirm, während ein Fehlschlag bei einer Benachrichtigung im Protokoll der Anwendung bleibt.

Im Hintergrund senden

Standardmäßig sendet BookStack E-Mails und Webhooks während der Anfrage, was die Seiten verlangsamen kann. Um in den Hintergrund zu wechseln, schreiben Sie QUEUE_CONNECTION=database in .env und lassen einen Dienst laufen, mit dem Beispiel, das die Dokumentation für eine Ubuntu-Installation per Skript gibt:

[Unit]
Description=BookStack Queue Worker

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable bookstack-queue.service
sudo systemctl start bookstack-queue.service

Ihre BookStack-Instanz absichern

Die Sicherheitsdokumentation nennt eine Liste, die Sie gleich bei der Installation abarbeiten:

1. Ändern Sie die Adresse und das Passwort des ersten Administrators.
2. Prüfen Sie, dass der Webserver nur den Ordner public ausliefert, vor allem wenn BookStack unter /var/www liegt.
3. Beschränken Sie den Datenbankbenutzer auf die Datenbank von BookStack allein.
4. Tragen Sie APP_URL ein, damit die vom System erzeugten Adressen nicht manipuliert werden können.
5. Prüfen Sie die Einstellungen für Registrierung und öffentlichen Zugriff und dann die Rollen.

Die Zwei-Faktor-Authentifizierung erzwingen Sie anschließend pro Rolle. Tragen Sie sich außerdem in die Sicherheits-Mailingliste des Projekts ein, um seine Warnungen zu erhalten. Die Adresse /status dient der Überwachung: Sie antwortet mit 200, wenn alles in Ordnung ist, sonst mit einem Fehlercode ab 400.

PHP zählt genauso viel wie BookStack. Das Projekt hat am 21. Oktober 2026 eine Warnung zu einem kritischen PHP-Update veröffentlicht, behoben in 8.5.12, 8.4.27, 8.3.36 und 8.2.35. Ubuntu veröffentlicht diese Korrekturen unter eigenen Paketnummern, etwa 8.3.6-0ubuntu0.24.04.13 für Ubuntu 24.04.

Lassen Sie für Ihre Inhalte die standardmäßig aktivierte Filterung eingeschaltet und lockern Sie sie nur auf Instanzen, auf denen ausschließlich vertrauenswürdige Personen schreiben. Geht ein Administratorkonto verloren, legt php artisan bookstack:create-admin ein anderes an, und php artisan bookstack:reset-mfa entfernt die Zwei-Faktor-Authentifizierung eines Benutzers.

Backups und Updates

Ein vollständiges Backup umfasst die Datenbank und die vier Dateiorte, die Ihrer Instanz eigen sind. Die Inhaltsexporte dienen etwas anderem: Die Dokumentation stellt klar, dass sie ein Backup nicht ersetzen.

sudo mysqldump -u root bookstack > bookstack.backup.sql
tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads themes

Die erste Zeile zielt auf eine Installation per Skript, bei der sich der MySQL-Benutzer root über sudo verbindet; anderswo schreiben Sie mysqldump -u bookstack -p bookstack. Legen Sie diese beiden Dateien getrennt ab, möglichst auf einer anderen Maschine. Das Archiv enthält .env, also APP_KEY und Ihre Passwörter: Behandeln Sie es wie ein Secret.

Wiederherstellen

Installieren Sie BookStack auf einer neuen Maschine, ohne php artisan migrate auszuführen, einen Schritt, den Sie im Skript auskommentieren, falls Sie es nutzen, und stellen Sie dann die Datenbank und die Dateien wieder her, wobei Sie den ursprünglichen APP_KEY behalten:

sudo mysql -u root bookstack < bookstack.backup.sql
tar -xvzf bookstack-files-backup.tar.gz

Ist die installierte Version neuer als das Backup, führen Sie anschließend php artisan migrate aus. Setzen Sie die Schreibrechte des Webservers auf den wiederhergestellten Ordnern zurück. Hat sich die Adresse geändert, korrigieren Sie APP_URL und führen bookstack:update-url aus.

Aktualisieren

Sichern Sie vor jedem Update die Datenbank und die Dateien und führen Sie dann, im Ordner von BookStack, aus:

git pull origin release
composer install --no-dev
php artisan migrate
php artisan cache:clear
php artisan config:clear
php artisan view:clear

Das Skript für Ubuntu 26.04 installiert BookStack ohne Composer. Die Update-Seite schlägt dann, als Beta, ./bookstack-system-cli download-vendor anstelle von composer install --no-dev vor. Dasselbe Werkzeug kann sichern und wiederherstellen, aber das Projekt hält es noch nicht für produktionsreif: Testen Sie es, bevor Sie sich darauf verlassen.

Die Dokumentation führt eine Liste von Hinweisen zu jeder Version, die Sie für die angestrebte Version lesen sollten. Einige Beispiele:

• Version 26.09: APP_KEY wird zur Pflicht.
• Version 26.05: Der Ordner storage/fonts muss für den Webserver beschreibbar bleiben, sonst können die PDF-Exporte scheitern.
• Version 26.03: Testen Sie nach dem Update den E-Mail-Versand.
• Version 25.11: große Änderungen an der Datenbank, deren Migration auf einer großen Instanz mehrere Minuten dauern kann.

Sicherheitslücken werden in Wartungsversionen behoben, wie der 26.09.3 vom 11. November 2026: Bilder und Zeichnungen einer Seite im Entwurf oder im Papierkorb blieben abrufbar und änderbar, und der persönliche Entwurf einer bearbeitenden Person konnte für andere sichtbar werden.

Wer was tut auf einem Managed VPS

Beim Selbsthosting müssen Sie neben der Anwendung auch den Server betreuen. Auf einem Managed VPS übernehmen unsere Teams den Server und betreuen Ihre Instanz proaktiv; BookStack bleibt Ihre Software, mit ihren Einstellungen und Daten.

Wenn unsere Teams lieber in der Anwendung selbst eingreifen sollen, wird diese Leistung nach Stunden oder pauschal abgerechnet, mit einem Kostenvoranschlag vor dem Eingriff.