Update

Einleitung

Diese Anleitung beschreibt Updates einer manuell installierten BookStack-Instanz auf Hosted Webspace. Zuerst folgt der allgemeine Ablauf, anschließend die konkret getestete Variante für das Wiki auf meinem STRATO-Webspace.

Am 27. August 2026 wurde die hier beschriebene Instanz damit erfolgreich von BookStack v26.05.2 auf v26.05.4 aktualisiert. Der Ablauf ist nicht auf diese Versionen beschränkt und kann auch für zukünftige Updates über den stabilen Branch release verwendet werden.

Die Erstinstallation steht unter Installation, die laufenden Einstellungen und Backups unter Konfiguration.

Standardupdate auf Hosted Webspace

Hinweise der Zielversion lesen

Vor jedem Update werden die offizielle Update-Anleitung und die dort verlinkten Hinweise zur Zielversion gelesen. Bei größeren Versionssprüngen können zusätzliche Arbeiten notwendig sein.

Ein Update sollte logischerweise nicht durchgeführt werden, solange ein bekanntes Problem mit PHP-Version, Erweiterungen, Datenbank oder Theme-Anpassungen offen ist.

Datenbank und Dateien sichern

Zu einer vollständigen Sicherung gehören die Datenbank sowie mindestens .env, public/uploads, storage/uploads und themes. In meinem Fall KANN man sich auf die Sicherung von STRATo verlassen (die sichern den Webspace und die Datenbank mindestens 1x täglich), muss man aber nicht :)

cd ~/wiki

tar -czf "$HOME/bookstack-files-before-update.tar.gz" \
  .env public/uploads storage/uploads themes

Die Datenbank wird zusätzlich mit mysqldump, phpMyAdmin oder der Backupfunktion des Providers exportiert. Beide Sicherungen werden außerhalb des Webspaces aufbewahrt. Ohne aktuelle Datenbanksicherung wird nicht migriert.

Git-Arbeitsstand prüfen

cd ~/wiki

git branch --show-current
git status --short
git remote -v

Erwartet wird der Branch release. git status --short darf keine ungeklärten Änderungen an BookStack-Kerndateien anzeigen. Eigene Anpassungen gehören in das Verzeichnis themes und nicht direkt in den Anwendungscode.

Update durchführen

Die Befehle werden einzeln ausgeführt. Nach einem Fehler wird angehalten und nicht einfach blind weitergemacht.

php artisan down

git pull --ff-only origin release

composer install \
  --no-dev \
  --optimize-autoloader \
  --no-interaction

php artisan migrate --force

php artisan cache:clear
php artisan config:clear
php artisan view:clear

php artisan up

Der Wartungsmodus bleibt aktiv, bis Git, Composer, Migration und Cache-Bereinigung erfolgreich abgeschlossen sind. Falls ein Schritt fehlschlägt, werden zuerst Fehlermeldung und Anwendungslog ausgewertet.

Funktion prüfen

Nach dem Update werden mindestens diese Wege getestet:

1. Startseite anonym öffnen.
2. Als Administrator anmelden.
3. Eine Seite öffnen, bearbeiten und speichern.
4. Suche sowie Bild- und Dateiupload prüfen.
5. Sitemap, RSS-Feed und PDF-Export testen.
6. Versionsanzeige und Anwendungslog kontrollieren.

tail -n 100 storage/logs/laravel.log

Angepasster Ablauf für STRATO

Umgebung vorbereiten

Die BookStack-Installation liegt bei mir unter ~/wiki. Auf der Kommandozeile wird nicht das allgemeine php verwendet, sondern fest das zu dieser Installation passende PHP 8.4 von STRATO. Composer wird ebenfalls mit genau diesem PHP gestartet.

cd ~/wiki

PHP=/opt/RZphp84/bin/php-cli
COMPOSER="$HOME/bin/composer"

"$PHP" -v
"$PHP" "$COMPOSER" --version
git branch --show-current
git status --short

Erwartet werden PHP 8.4, Composer 2.x, der Branch release und ein geklärter Git-Arbeitsstand.

STRATO-Backup erstellen

Die Datenbank wird im STRATO-Kundenbereich beziehungsweise mit phpMyAdmin exportiert. Danach werden die instanzspezifischen Dateien außerhalb des öffentlichen Verzeichnisses archiviert:

cd ~/wiki

tar -czf "$HOME/bookstack-files-before-update.tar.gz" \
  .env public/uploads storage/uploads themes

Das Archiv und der Datenbankexport werden anschließend auf ein anderes System kopiert. Das Archiv bleibt nicht dauerhaft auf dem Webspace liegen.

STRATO-Update durchführen

cd ~/wiki

PHP=/opt/RZphp84/bin/php-cli
COMPOSER="$HOME/bin/composer"

"$PHP" artisan down

git pull --ff-only origin release

"$PHP" -d memory_limit=-1 "$COMPOSER" install \
  --no-dev \
  --optimize-autoloader \
  --no-interaction

"$PHP" artisan migrate --force

"$PHP" artisan cache:clear
"$PHP" artisan config:clear
"$PHP" artisan view:clear

#Für dieses Update, weil eine neue Funktion dazu gekommen ist.
mkdir -p storage/fonts
chmod -R u+rwX storage bootstrap/cache public/uploads storage/fonts

"$PHP" artisan up

Der unbegrenzte PHP-Speicher gilt nur für diesen Composer-Aufruf. storage/fonts und die übrigen Laufzeitverzeichnisse erhalten Schreibrechte für den Hostingbenutzer; pauschale Rechte wie 777 sind nicht notwendig.

Heutiges Update auf v26.05.4

Beim Update am 27. August 2026 war der Ausgangsstand v26.05.2. Nach dem Backup wurde der aktuelle Stand des Branches release mit git pull --ff-only origin release übernommen. Anschließend wurden die PHP-Abhängigkeiten mit dem STRATO-PHP aktualisiert, die Datenbankmigrationen ausgeführt und die Caches geleert.

Der Wartungsmodus konnte danach regulär beendet werden. Die Versionsanzeige meldete v26.05.4; die Weboberfläche und die öffentlich erreichbaren Funktionen liefen anschließend ohne erkennbares Sicherheits- oder Funktionsproblem.

Für das nächste Update wird (hoffentlich) derselbe Ablauf verwendet. Lediglich die Versionshinweise, Systemanforderungen und eventuell genannten Zusatzschritte müssen vorher erneut anhand der offiziellen Dokumentation geprüft werden. Sollten Anpassungen oder Änderungen notwendig sein, gibt es hier ein kleines Update im Artikel.

Fehlerfall

Schlägt git pull oder Composer fehl, wird keine Datenbankmigration gestartet. Schlägt die Migration fehl, bleibt die Anwendung im Wartungsmodus, bis die Ursache geklärt ist.

cd ~/wiki

PHP=/opt/RZphp84/bin/php-cli
tail -n 100 storage/logs/laravel.log
git status --short

Erst nach erfolgreicher Fehlerbehebung wird die Befehlsfolge fortgesetzt. Ist eine sichere Reparatur nicht möglich, werden Dateien und Datenbank gemeinsam aus demselben Backupstand wiederhergestellt.

Abschlussprüfung

Nach jedem Update sollten Versionsanzeige, Logs und die für diese Instanz wichtigen Funktionen geprüft werden. Erst danach gilt das Update als abgeschlossen. Besonders wichtig sind der anonyme Seitenaufruf, Anmeldung, Bearbeitung, Uploads, Suche, Sitemap, RSS-Feed und PDF-Export.