Installation

Updates & Upgrades

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. Der genaue Ablauf hängt davon ab, ob du den latest-Tag oder eine gepinnte Version verwendest.

Du aktualisierst eine bestehende Instanz auf 2.0.0?

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.

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 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 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 größeren Updates die Datenbank (per pg_dump), die Uploads und die .env. 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 oder die Startreihenfolge der Worker anpassen. Hole deshalb auch die Compose-Datei aus dem Repository und vergleiche die .env.example mit deiner .env, ob neue Variablen dazugekommen sind: 

cd fedisuite
git pull
diff .env.example .env   # zeigt neue oder entfernte Variablen
docker compose config    # prüft die zusammengesetzte Konfiguration

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.

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).

Variante A: latest-Tag (Standard)

Steht in deiner .env der Standard FEDISUITE_IMAGE=christinloehner/fedisuite:latest, reichen nach dem git pull zwei Befehle:

bash 
# Neues Image laden
docker compose pull

# Container mit neuem Image neu erstellen
docker compose up -d

docker compose pull lädt das aktuelle latest-Image von Docker Hub. Ist es lokal schon vorhanden, passiert nichts. Danach erstellt docker compose up -d die Container neu, deren Image sich geändert hat. Weil die Compose-Datei pull_policy: always setzt, prüft auch ein einfaches docker compose up -d (etwa nach einer Konfigurationsänderung) auf ein neueres Image und kann dadurch ein Update auslösen. Für ARM64-Server gilt dasselbe mit dem Tag arm64-latest.

Hinweis: Admins sehen in der Oberfläche einen Hinweis, wenn auf Docker Hub eine neuere Version als die laufende veröffentlicht ist. Die Prüfung wird bis zu 30 Minuten zwischengespeichert.

Variante B: Gepinnter Version-Tag

Wer Updates bewusst steuern und vorher testen möchte, pinnt das Image auf eine Version, zum Beispiel christinloehner/fedisuite:2.0.0. Dann holt docker compose pull keine neueren Versionen, weil der Tag fest auf eine Version zeigt. Du musst den Tag selbst in der .env ändern. Die Versionsnummern in den Beispielen unten sind Platzhalter.

1

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.0.0.

2

FEDISUITE_IMAGE in der .env anpassen

Öffne die .env und ändere den Tag auf die neue Version:

Vorher

FEDISUITE_IMAGE=christinloehner/fedisuite:1.7.3

Nachher

FEDISUITE_IMAGE=christinloehner/fedisuite:2.0.0
3

Image laden und Container neu erstellen

bash 
# Neuen Tag laden
docker compose pull

# Container mit neuem Image neu erstellen
docker compose up -d
latest vs. gepinnter Tag: Mit latest bist du nach docker compose pull sofort auf dem neuesten Stand, und weil pull_policy: always gesetzt ist, kann sogar ein einfaches docker compose up -d aktualisieren. Mit einem gepinnten Tag entscheidest du, wann und auf welche Version du wechselst. Für Instanzen mit vielen Nutzer*innen eignet sich der gepinnte Tag, weil du vorher testen und ein Backup ziehen kannst.

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 (postgres:15-alpine) bleibt unverändert. Der Ablauf:

1

Alte Container werden gestoppt

Docker stoppt die laufenden Container von App und Workern geordnet. Ab jetzt ist FediSuite kurz nicht erreichbar.

2

Neuer app-Container wird erstellt

Docker erstellt den Container aus dem neuen Image, mit denselben Volumes, Netzwerken und Umgebungsvariablen.

3

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.

4

App wird healthy, Worker starten

Sobald /api/health antwortet, gilt die app als healthy. Erst dann starten die Worker. FediSuite ist wieder erreichbar.

Worker werden mit aktualisiert: 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.

Mit gepinntem Tag: Version in der .env zurücksetzen

bash 
# .env: FEDISUITE_IMAGE zurück auf die alte Version setzen (Beispiel)
# FEDISUITE_IMAGE=christinloehner/fedisuite:1.7.3

# Container mit dem alten Image neu erstellen
docker compose up -d

Mit latest: alten Version-Tag eintragen

Bei latest zeigt der Tag nach dem Update auf das neue Image. Für den Rückweg trägst du den Tag der vorigen Version in der .env ein. Die alten Tags liegen auf Docker Hub, lokal vorhandene Images listet docker images christinloehner/fedisuite auf.

bash 
# Lokal vorhandene Images auflisten
docker images christinloehner/fedisuite

# Gewünschten Version-Tag in der .env setzen und neu starten
docker compose up -d
Datenbank-Rollback: Hat das Update Datenbankmigrationen ausgeführt, reicht ein Container-Rollback womöglich nicht. FediSuite führt Migrationen nur vorwärts aus, und die neue Struktur ist nicht zwingend mit der alten App-Version kompatibel. Dann hilft nur ein Restore der Datenbank vom Stand vor dem Update, siehe Backup & Restore.

Reverse Proxy

Backup & Restore