Aktualisierung und Upgrade
Da FediSuite vollständig auf Docker basiert, besteht ein Update aus der aktualisierten Compose-Datei, einem neuen Image und neu erstellten Containern. Datenbankmigrationen laufen beim Start der App automatisch ab. Die Images trägst du mit einem festen Versions-Tag ein und lädst sie bewusst herunter.
Das ist kein gewöhnliches Update: Du brauchst vor dem ersten Start ein Datenbank-Backup und einen dauerhaften ACCOUNT_ENCRYPTION_KEY. Folge bitte der Schritt-für-Schritt-Anleitung für das Upgrade auf 2.0.0, nicht nur den allgemeinen Befehlen unten.
Neue Installationen nutzen PostgreSQL 18. Bestehende Instanzen stellst du mit einem Backup und einer Wiederherstellung um, ein bloßer Tag-Wechsel genügt nicht. Folge der Schritt-für-Schritt-Anleitung zum Wechsel von PostgreSQL 15 auf 18.
Auf dieser Seite
Wie Updates bei Docker funktionieren
FediSuite wird als fertiges Docker-Image auf Docker Hub veröffentlicht. Auf deinem Server liegt kein Quellcode, den du anfassen müsstest: Du tauschst das Image aus.
docker compose pull --policy always lädt die Images herunter, die in der Compose-Datei stehen. docker compose up -d erstellt dann die Container neu, deren Image sich geändert hat. Die Compose-Datei lädt Images nie von selbst herunter (pull_policy: never); das Update geschieht also nur, wenn du es auslöst. Die Compose-Datei selbst kommt aus dem Repository FediSuite-Self-Hosting und wird per git pull aktualisiert.
Deine Daten (Datenbank in ./postgres/, Uploads in ./uploads/, Plugins in ./plugins/, Logs in ./logs/) liegen in Bind Mounts außerhalb der Container und bleiben bei Updates erhalten.
Vor dem Update
1. Changelog lesen
Wirf vor jedem Update einen Blick in den Changelog. Bei Sprüngen über mehrere Versionen oder bei einer neuen Hauptversion (zuletzt 2.0.0 mit überarbeiteter Navigation, Entwürfen, Content-Kalender, Labels und Kampagnen) lohnt es sich, alle Einträge dazwischen zu lesen. Neue Funktionen lassen sich über Schalter abschalten, siehe die Seite Umgebungsvariablen.
Changelog auf Forgejo ansehen (öffnet in neuem Tab)2. Backup erstellen
Sichere vor jedem Update die Datenbank, die Uploads, die Plugins und die .env. Das erledigt das mitgelieferte Skript scripts/backup.sh in einem Schritt, am besten bei angehaltenen Diensten app und Workern. Mit einem Migrationsschritt, der die Datenbank verändert, ist ein Zurück nur über das Backup möglich. Eine ausführliche Anleitung steht auf der Seite Backup & Restore.
3. Compose-Datei aktualisieren
Ein neues Image ändert die docker-compose.yml nicht. Neue Fassungen können zum Beispiel Healthchecks, Umgebungsvariablen, das PostgreSQL-Image oder die Startreihenfolge der Worker anpassen. Hole deshalb auch die Compose-Datei und die Skripte aus dem Repository und vergleiche die .env.example mit deiner .env, ob neue Variablen dazugekommen sind:
cd fedisuite
git pull --ff-only
diff .env.example .env # zeigt neue oder entfernte Variablen
./scripts/check-config.sh # prüft Tags, PostgreSQL-Image und Mount-Pfad
Bei diff erscheinen immer auch Unterschiede in deinen eigenen Werten; achte nur auf Variablennamen, die in deiner .env fehlen. Hast du die docker-compose.yml selbst bearbeitet (zum Beispiel für Traefik), meldet git pull einen Konflikt. Lege solche Anpassungen künftig in eine docker-compose.override.yml, die das Repository ignoriert. Gib docker compose config nicht aus, ohne --quiet anzuhängen, und poste die Ausgabe nirgends: Sie enthält die Werte aus deiner .env.
4. Kurze Downtime einplanen
Während docker compose up -d die Container neu erstellt und die app die Datenbankmigrationen ausführt, ist FediSuite nicht erreichbar. Meist dauert das Sekunden bis wenige Minuten. Der Healthcheck der App erlaubt bei langen Migrationen bis zu zehn Minuten Startzeit (start_period).
Update durchführen (fester Versions-Tag)
Die aktuelle Self-Hosting-Vorlage verwendet ausschließlich feste Versions-Tags und lädt Images nie von selbst herunter (pull_policy: never). Ein Update ist deshalb immer ein bewusster Ablauf in vier Schritten. Die Versionsnummern in den Beispielen sind Platzhalter.
Ziel-Version im Changelog ermitteln
Im Changelog (öffnet in neuem Tab) steht, welche Versionen es gibt und was sich ändert. Versionsnummern haben die Form MAJOR.MINOR.PATCH, zum Beispiel 2.1.0.
FEDISUITE_IMAGE in der .env anpassen
Öffne die .env und ändere den Tag auf die neue Version. Auf ARM64-Servern behältst du das Präfix arm64- bei.
Vorher
FEDISUITE_IMAGE=christinloehner/fedisuite:2.0.3
Nachher
FEDISUITE_IMAGE=christinloehner/fedisuite:2.1.0
Stoppen, sichern und prüfen
Halte App und Worker an, erstelle ein Backup und prüfe die Konfiguration. Das Prüfskript meldet Configuration is valid., wenn Tag, PostgreSQL-Image und Mount-Pfad zusammenpassen. Mehr zum Backup: Backup & Restore.
# App und Worker anhalten (die Datenbank läuft weiter)
docker compose stop app worker1 worker2
# Backup mit Datenbank, .env, Uploads und Plugins
./scripts/backup.sh /pfad/zum/backup-speicher
# Konfiguration prüfen
./scripts/check-config.sh
Image laden und Container neu erstellen
docker compose pull --policy always lädt die Images aller Dienste neu. Das schließt das PostgreSQL-Image ein: Gibt es innerhalb von PostgreSQL 18 ein neueres Nebenversions-Image, wird der db-Container dabei ebenfalls neu erstellt. Das ist ohne Datenmigration möglich, die Daten bleiben erhalten. Willst du nur FediSuite aktualisieren, nutze docker compose pull --policy always app: Die Worker verwenden dasselbe Image.
# Neues Image laden
docker compose pull --policy always
# Container mit neuem Image neu erstellen
docker compose up -d
latest lehnt das Prüfskript ab. Ermittle die Version, die du gerade betreibst, mit docker compose exec -T app printenv VITE_APP_VERSION und trage sie als FEDISUITE_IMAGE=christinloehner/fedisuite:<Version> ein, bevor du die Compose-Datei aktualisierst. Außerdem braucht die neue Compose-Datei die Einstellungen POSTGRES_IMAGE, POSTGRES_DATA_PATH und POSTGRES_DATA_TARGET in der .env. Für eine bestehende Installation mit PostgreSQL 15 folge der Anleitung PostgreSQL 15 auf 18 aktualisieren; sie beschreibt auch, wie du die Compose-Datei zuerst sicher umstellst.
Was beim Update passiert
docker compose up -d erkennt, dass für einen oder mehrere Services ein neues Image vorliegt, und erstellt diese Container neu. Die Datenbank bleibt unverändert, solange sich ihr Image nicht ändert. Der Ablauf:
Alte Container werden gestoppt
Docker stoppt die laufenden Container von App und Workern geordnet. Ab jetzt ist FediSuite kurz nicht erreichbar.
Neuer app-Container wird erstellt
Docker erstellt den Container aus dem neuen Image, mit denselben Volumes, Netzwerken und Umgebungsvariablen.
Datenbankmigrationen laufen automatisch
Die app führt beim Start init-db.js aus. Das Skript ist idempotent: Es legt fehlende Tabellen und Spalten an und bringt das Schema auf den aktuellen Stand, bestehende Daten bleiben. Schlägt ein Schritt fehl, startet der Server nicht. Du führst keine Migrationsbefehle selbst aus.
App wird healthy, Worker starten
Sobald /api/health antwortet, gilt die app als healthy. Erst dann starten die Worker. FediSuite ist wieder erreichbar.
docker compose up -d aktualisiert alle Services mit neuem Image, also auch worker1 und worker2. Du musst nichts getrennt anstoßen.
Update verifizieren
Prüfe nach dem Update, ob alle Container sauber hochgefahren sind:
Status aller Container prüfen
Alle Container sollten running zeigen, db und app zusätzlich healthy. Die Worker starten erst, wenn die App healthy ist.
docker compose ps
Startlogs der App prüfen
Hier siehst du, ob die Datenbankinitialisierung erfolgreich war (Database initialized successfully) und der Server gestartet ist (Server running on port 3000).
docker compose logs app --tail=50
Health-Endpunkt prüfen
Liefert JSON mit status: ok und db: connected, sobald App und Datenbank bereit sind.
curl -s http://127.0.0.1:3000/api/health
Worker-Logs prüfen
Beim Start loggen die Worker, welche Jobs sie übernehmen (zum Beispiel [PostsRefresh], [ReachRefresh] Enabled).
docker compose logs worker1 --tail=30
Welches Image läuft gerade?
Zeigt Repository, Tag und Image-ID der Container.
docker compose images
Rollback
Stimmt nach einem Update etwas nicht, kannst du auf die vorherige Version zurückwechseln. Das gilt für die Container. Ob die Datenbank dazu passt, hängt davon ab, ob das Update das Schema verändert hat.
Version in der .env zurücksetzen
Trage in der .env den Tag der vorigen Version ein. Die Compose-Datei lädt nichts von selbst nach: Ist das alte Image lokal noch vorhanden (prüfe das mit docker images christinloehner/fedisuite), genügt docker compose up -d. Fehlt es, hole es vorher mit docker compose pull --policy always app.
# Lokal vorhandene Images auflisten
docker images christinloehner/fedisuite
# .env: FEDISUITE_IMAGE zurück auf die alte Version setzen (Beispiel)
# FEDISUITE_IMAGE=christinloehner/fedisuite:2.0.3
# Container mit dem alten Image neu erstellen
docker compose up -d