PostgreSQL 15 auf 18 aktualisieren

1. Überblick: Was passiert und muss ich das jetzt tun?

Neue FediSuite-Installationen laufen mit PostgreSQL 18. Bestehende Installationen wurden nicht automatisch umgestellt, weil ein Wechsel der Hauptversion immer eine Datenmigration erfordert. PostgreSQL 15 bekommt noch bis zum 11. November 2027 Sicherheits- und Fehlerkorrekturen, PostgreSQL 18 bis zum 14. November 2030. Du musst also nicht sofort umstellen, solltest den Wechsel aber vor dem Ende der Unterstützung einplanen.

So läuft der Wechsel ab:

1. Du sicherst die gesamte Instanz (Datenbank, .env, Uploads, Plugins).
2. Du startest PostgreSQL 18 mit einem neuen, leeren Datenverzeichnis (./postgres18).
3. Du spielst die gesicherten Daten dort ein.
4. Du startest die App und die Worker wieder.

Das alte PostgreSQL-15-Verzeichnis ./postgres wird dabei nur gelesen, nicht verändert. Solange App und Worker noch nicht mit PostgreSQL 18 gelaufen sind, kannst du jederzeit ohne Datenverlust zu PostgreSQL 15 zurückkehren (siehe Rollback).

Ausfallzeit: Während des Wechsels sind FediSuite und alle Worker angehalten. Niemand kann sich anmelden, und es werden keine Beiträge veröffentlicht oder Statistiken aktualisiert. Bei einer kleinen Instanz dauert das meist nur wenige Minuten, bei vielen Gigabyte an Daten entsprechend länger. Plane ein Wartungsfenster außerhalb wichtiger Termine ein. Beiträge, die in dieser Zeit fällig werden, holt der Scheduler nach dem Start nach; verlasse dich bei zeitkritischen Beiträgen aber nicht darauf.

Reihenfolge der Updates: Ändere in diesem Wartungsfenster nur die Datenbank. Aktualisiere FediSuite nicht gleichzeitig auf eine neue Version. Falls du noch eine Version vor 2.0.0 betreibst, führe zuerst das Upgrade auf 2.0.0 durch und wechsle erst danach die Datenbank.

2. Vorbereitung und Bestandsaufnahme

Verbinde dich per SSH mit deinem Server und wechsle in das Verzeichnis deiner Installation, also dorthin, wo docker-compose.yml und .env liegen. Der Pfad unten ist nur ein Beispiel. Alle weiteren Befehle führst du in diesem Verzeichnis aus.

cd /pfad/zu/deiner/fedisuite-installation
pwd
ls -la .env docker-compose.yml scripts

Beide Dateien müssen angezeigt werden. Das Verzeichnis scripts gibt es vielleicht noch nicht, es kommt in Schritt 4 dazu. Arbeite nicht in einer frisch geklonten Kopie: Dort liegen weder deine Daten noch deine Einstellungen.

Hinweis zu sudo: Wenn dein Benutzer Docker nur mit sudo verwenden darf, setze sudo vor jeden docker-Befehl und vor jedes ./scripts/…-Skript in dieser Anleitung.

Läuft wirklich PostgreSQL 15?

docker compose ps
docker compose exec -T db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Atc "SHOW server_version;"'

Die erste Ausgabe zeigt alle Dienste (db, app, worker1, worker2) mit dem Status healthy. Die zweite Ausgabe ist die Datenbankversion, zum Beispiel 15.19. Steht dort bereits eine 18.…, bist du fertig und musst nichts tun. Steht dort weder 15 noch 18, mach hier nicht weiter und frage im Support-Forum nach.

Welche FediSuite-Version läuft?

docker compose exec -T app printenv VITE_APP_VERSION

Die Ausgabe ist die Versionsnummer, zum Beispiel 2.1.0. Notiere sie: Du trägst sie in Schritt 3 ein. Wenn der Befehl keine Zahl ausgibt, findest du die Version im Changelog oder über den Image-Tag in deiner .env, sofern dort kein latest steht.

Ist genug Speicherplatz frei?

Während des Wechsels existieren die alte Datenbank, das Backup und die neue Datenbank gleichzeitig. Plane etwa das Dreifache der aktuellen Datenbankgröße ein.

df -h .
sudo du -sh postgres uploads

df -h . zeigt den freien Platz (Spalte Verfügbar bzw. Avail), du -sh die Größe von Datenbank und Uploads. Das Datenbankverzeichnis gehört dem Datenbank-Benutzer, deshalb braucht du hier sudo. Hast du ein anderes Datenverzeichnis als ./postgres eingerichtet, passe den Namen an.

Eigene Speicherorte: Das mitgelieferte Backup-Skript und diese Anleitung gehen von der Standardinstallation aus: Datenbank in ./postgres, dazu die Ordner uploads, plugins und logs neben der Compose-Datei. Nutzt du benannte Docker-Volumes oder andere Pfade, sichere diese Speicherorte zusätzlich selbst (siehe Backup & Restore) und frage bei Unsicherheit zuerst im Support-Forum nach.

3. Neue Einstellungen in der .env ergänzen

Die aktuelle Compose-Datei von FediSuite liest drei neue Einstellungen aus der .env und verlangt außerdem einen festen FediSuite-Tag. Die neuen Einstellungen legen fest, welches PostgreSQL-Image läuft, wo seine Daten liegen und wie das Datenverzeichnis im Container eingehängt wird. Ohne sie bricht Compose bewusst mit einer Fehlermeldung ab, damit nichts unbeabsichtigt umgestellt wird. Ergänze sie jetzt zuerst mit den Werten für PostgreSQL 15. Dadurch ändert sich noch nichts an deiner Datenbank.

Lege zunächst eine Sicherheitskopie deiner .env an. Die Kopie enthält deine Passwörter und bekommt deshalb nur Rechte für dich:

cp -p .env .env.vor-postgres-18
chmod 600 .env.vor-postgres-18

Öffne dann die .env in einem Editor, zum Beispiel mit nano .env, und füge diese drei Zeilen am Ende hinzu:

POSTGRES_IMAGE=postgres:15-alpine
POSTGRES_DATA_PATH=./postgres
POSTGRES_DATA_TARGET=/var/lib/postgresql/data

Suche außerdem die Zeile FEDISUITE_IMAGE=. Sie muss auf die genaue Version zeigen, die du gerade betreibst (aus Schritt 2), nicht auf latest. Fehlt die Zeile, füge sie hinzu. Beispiel für Version 2.1.0:

FEDISUITE_IMAGE=christinloehner/fedisuite:2.1.0

Betreibst du das Image mit einem besonderen Tag-Präfix, etwa arm64- auf ARM-Servern, behalte dieses Präfix bei und ersetze nur die Versionsnummer.

In nano speicherst du mit Strg+O und Enter und verlässt den Editor mit Strg+X. Ändere sonst nichts in der Datei, vor allem nicht DATABASE_URL, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, JWT_SECRET und ACCOUNT_ENCRYPTION_KEY. Prüfe das Ergebnis mit diesem Befehl, der keine Passwörter ausgibt:

grep -E '^(FEDISUITE_IMAGE|POSTGRES_IMAGE|POSTGRES_DATA_PATH|POSTGRES_DATA_TARGET)=' .env

Es müssen genau vier Zeilen erscheinen, jede nur einmal. Doppelte Zeilen verwirren Compose und die Prüfskripte: Entferne dann die überzählige.

4. Self-Hosting-Dateien aktualisieren

Du brauchst die aktuelle docker-compose.yml und den Ordner scripts (Prüf-, Backup- und Wiederherstellungsskripte) aus dem Self-Hosting-Repository. Wenn dein Verzeichnis ein Git-Checkout ist (es gibt einen Ordner .git), aktualisierst du es so:

git status --short
git pull --ff-only

git status --short listet Änderungen an versionierten Dateien. Deine .env, die meisten Datenordner und eine docker-compose.override.yml werden von Git ignoriert. Zeilen mit ?? (zum Beispiel ?? plugins/) sind nicht versionierte Ordner oder Dateien und stören git pull nicht. Taucht nur so etwas auf oder ist die Liste leer, läuft git pull --ff-only ohne Probleme durch. Zeilen mit M davor sind geänderte versionierte Dateien, siehe unten.

Wenn du die docker-compose.yml selbst geändert hast (zum Beispiel Traefik-Labels oder Netzwerke), listet git status --short diese Datei, und git pull bricht mit einer Fehlermeldung ab. Erzwinge dann nichts. Gehe so vor:

1. Sichere deine angepasste Datei: cp docker-compose.yml ~/docker-compose.yml.vor-postgres-18
2. Setze die Datei auf die Vorlage zurück und hole die Aktualisierung: git checkout -- docker-compose.yml, danach git pull --ff-only
3. Übertrage deine Anpassungen anschließend wieder. Am einfachsten legst du sie in eine Datei docker-compose.override.yml im selben Verzeichnis: Compose liest sie automatisch zusätzlich, und Git ignoriert sie. Für Traefik gibt es die Vorlage docker-compose.traefik.example.yml im Repository.

Hast du gar keinen Git-Checkout, lade docker-compose.yml und den Ordner scripts aus dem Repository herunter und lege sie in dein Installationsverzeichnis. Überschreibe dabei nicht deine .env, und kopiere die .env.example nicht über sie. Mach scripts/*.sh ausführbar: chmod +x scripts/*.sh.

Prüfe nun die Konfiguration. Der Befehl startet oder ändert nichts:

./scripts/check-config.sh
docker compose ps

Erwartet wird die Meldung Configuration is valid., und docker compose ps zeigt weiterhin alle vier Dienste als healthy. Deine Instanz läuft bis hierher unverändert.

Bei einer Fehlermeldung ist fast immer eine der vier Einstellungen aus Schritt 3 vergessen oder falsch geschrieben. Die Meldung nennt die Einstellung; siehe auch Fehler und Lösungen.

5. Anwendung anhalten und Backup erstellen

Jetzt beginnt die Ausfallzeit. Halte zuerst App und Worker an. Die Datenbank bleibt für das Backup eingeschaltet. Danach erstellt das Skript backup.sh ein Archiv mit der Datenbank, der .env, der Compose-Datei sowie den Ordnern uploads und plugins:

docker compose stop app worker1 worker2
mkdir -p "$HOME/fedisuite-backups"
./scripts/backup.sh "$HOME/fedisuite-backups"

Hast du zusätzliche Worker-Dienste (zum Beispiel worker3), halte auch diese an. docker compose ps --services listet alle Dienste.

Das Skript meldet am Ende Backup created: … mit dem Dateinamen, der Datum und Uhrzeit enthält, etwa fedisuite-20261011T173000Z.tar.gz. Es prüft den Datenbank-Dump bereits beim Erstellen. Kontrolliere trotzdem, ob das Archiv existiert und eine sinnvolle Größe hat:

ls -lh "$HOME/fedisuite-backups"
tar -tzf "$HOME/fedisuite-backups/DATEINAME.tar.gz"

Ersetze DATEINAME durch den Namen aus der Ausgabe von ls. Die Liste muss mindestens database.dump, manifest.txt, .env, docker-compose.yml, uploads/ und plugins/ enthalten.

Läuft das Backup nicht durch, beende hier und lies die Fehlermeldung. Starte dann mit docker compose start app worker1 worker2 die Anwendung wieder, damit deine Instanz erreichbar bleibt. Ohne ein geprüftes Backup stellst du die Datenbank nicht um.

6. PostgreSQL 18 mit leerer Datenbank starten

Halte zuerst die alte Datenbank an. Ihre Dateien in ./postgres bleiben unangetastet erhalten:

docker compose stop db

Öffne die .env erneut (nano .env) und ändere genau diese drei Zeilen, die du in Schritt 3 ergänzt hast:

POSTGRES_IMAGE=postgres:18-alpine
POSTGRES_DATA_PATH=./postgres18
POSTGRES_DATA_TARGET=/var/lib/postgresql

Alles andere in der Datei bleibt unverändert, insbesondere DATABASE_URL, POSTGRES_DB, POSTGRES_USER und POSTGRES_PASSWORD. Die neue Datenbank wird mit denselben Zugangsdaten angelegt. Beachte den Unterschied bei POSTGRES_DATA_PATH (neuer Ordner ./postgres18) und POSTGRES_DATA_TARGET (ohne /data am Ende).

Prüfe die Konfiguration, lade die Images und starte nur die Datenbank:

./scripts/check-config.sh
docker compose pull --policy always db app
docker compose up -d db
docker compose ps

Das Skript muss wieder Configuration is valid. melden. Der Download kann einen Moment dauern. Kennt dein Docker den Schalter --policy nicht (sehr alte Compose-Version), nutze stattdessen docker pull postgres:18-alpine und docker pull mit dem Image-Namen aus deiner FEDISUITE_IMAGE-Zeile. Die Compose-Datei verwendet pull_policy: never: Docker lädt Images nie von selbst nach, deshalb ist dieser Schritt nötig. Er holt auch das FediSuite-Image mit dem festen Tag, damit es später bereitsteht.

Der erste Start legt ein neues Datenbank-Cluster an. Warte, bis db in der Ausgabe von docker compose ps als healthy angezeigt wird. Das dauert meist einige Sekunden. Prüfe dann die Version und dass die Datenbank noch leer ist:

docker compose exec -T db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Atc "SHOW server_version;" -c "\dt"'

Die Ausgabe enthält eine Zeile mit der Version, die mit 18. beginnt (zum Beispiel 18.6), und die Meldung Did not find any tables. Das ist richtig: Die neue Datenbank ist noch leer, die Daten kommen im nächsten Schritt.

7. Daten in PostgreSQL 18 einspielen

Das Skript restore-database.sh spielt nur die Datenbank aus dem Archiv ein. Es berührt .env, Uploads und Plugins nicht. Es löscht die (leere) Datenbank in PostgreSQL 18 und erstellt sie neu, bevor es die Daten einspielt. Aus Sicherheitsgründen verlangt es das Flag --confirm-replace-database und läuft nur, wenn App und Worker angehalten sind und die Datenbank läuft. Beides ist jetzt der Fall.

Verwende den Dateinamen deines Archivs aus Schritt 5:

./scripts/restore-database.sh "$HOME/fedisuite-backups/DATEINAME.tar.gz" --confirm-replace-database

Bei Erfolg endet die Ausgabe mit Database restored.. Bei einer größeren Datenbank dauert das einige Minuten. Unterbrich den Vorgang nicht. Kontrolliere danach, dass die Daten da sind:

docker compose exec -T db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Atc "SELECT count(*) AS benutzer FROM users;" -c "SELECT count(*) AS konten FROM accounts;"'

Die Zahlen müssen zu deiner Instanz passen: mindestens ein Benutzer (der Admin) und die Anzahl der verbundenen Konten. Bricht das Einspielen mit einem Fehler ab, wurde alles in einer Transaktion zurückgerollt und die Datenbank ist leer. Dein Backup und das alte Datenverzeichnis sind unverändert. Siehe Fehler und Lösungen.

8. FediSuite starten und prüfen

Starte zuerst nur die App und warte, bis sie gesund ist. Die App prüft beim Start das Datenbankschema und ergänzt es bei Bedarf. Erst danach startest du die Worker:

docker compose up -d app
docker compose ps
docker compose logs --tail=50 app

Wiederhole docker compose ps, bis app als healthy erscheint. Das kann bis zu einer Minute dauern. Die Logs sollten keine Fehlermeldungen zur Datenbank enthalten. Starte jetzt die Worker:

docker compose up -d worker1 worker2
docker compose ps
docker compose logs --tail=50 worker1 worker2 db

Hat deine Installation weitere Worker, starte sie ebenfalls. Nach etwa einer Minute müssen db, app, worker1 und worker2 als healthy angezeigt werden, und keiner darf ständig neu starten.

Prüfliste:

• Öffne deine Instanz im Browser und melde dich mit einem bestehenden Konto an.
• Prüfe, ob deine verbundenen Fediverse-Konten, die Statistiken und die Beitragshistorie vorhanden sind.
• Prüfe geplante Beiträge und Entwürfe.
• Prüfe, ob hochgeladene Bilder und installierte Plugins noch funktionieren.
• Prüfe, ob die Datenbank wirklich PostgreSQL 18 ist: docker compose exec -T db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Atc "SHOW server_version;"'
• Beobachte die Logs in den nächsten Stunden auf Fehler: docker compose logs --since=1h app worker1 worker2.

Hinweis: Nach dem Einspielen sammelt PostgreSQL erst neue Statistiken über die Tabellen. In den ersten Minuten können einzelne Abfragen daher etwas langsamer sein; das ist normal und legt sich von selbst.

9. Nach dem Wechsel

• Altes Datenverzeichnis aufbewahren: Lass ./postgres und das Backup-Archiv mindestens so lange bestehen, bis die neue Datenbank mehrere Tage oder Wochen fehlerfrei gelaufen ist und du ein neues Backup mit PostgreSQL 18 hast. Beide enthalten weiterhin alle Daten und Zugangsdaten und müssen geschützt bleiben.
• Neues Backup erstellen: Erstelle sobald die Instanz stabil läuft ein frisches Backup (./scripts/backup.sh "$HOME/fedisuite-backups") und sichere es extern. Ein Backup der alten Version ersetzt das nicht. Wie du Backups automatisierst und testest, steht unter Backup & Restore.
• Die .env aktuell halten: Sichere die geänderte .env (inklusive ACCOUNT_ENCRYPTION_KEY) neu. Die Kopie .env.vor-postgres-18 kannst du löschen, sobald alles läuft.
• Altes Verzeichnis löschen (optional, später): Wenn nach einiger Zeit alles stabil läuft, kannst du Platz freigeben. Prüfe vorher mit grep POSTGRES_DATA_PATH .env, dass dort ./postgres18 steht, und dass ein aktuelles Backup mit PostgreSQL 18 außerhalb des Servers liegt. Lösche das alte Verzeichnis erst dann, und nur dieses: sudo rm -r ./postgres. Danach ist ein Rollback auf PostgreSQL 15 nicht mehr möglich.

10. Zurück zu PostgreSQL 15 (Rollback)

Das alte Datenverzeichnis ./postgres wurde während des Wechsels nie von PostgreSQL 18 verändert. Du kannst deshalb zurückkehren, solange du es nicht gelöscht hast.

docker compose stop
nano .env

POSTGRES_IMAGE=postgres:15-alpine
POSTGRES_DATA_PATH=./postgres
POSTGRES_DATA_TARGET=/var/lib/postgresql/data

./scripts/check-config.sh
docker compose up -d
docker compose ps

Starte PostgreSQL 18 niemals auf dem Verzeichnis ./postgres und PostgreSQL 15 niemals auf ./postgres18.

Fehler und Lösungen