Installation

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.

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.

Läuft deine Datenbank noch mit PostgreSQL 15?

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.

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.

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

2

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
3

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.

bash
# 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
4

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.

bash
# Neues Image laden
docker compose pull --policy always

# Container mit neuem Image neu erstellen
docker compose up -d
Du nutzt noch den Tag latest? Die aktuelle Compose-Datei verlangt einen festen Tag; 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.
Mit festem Tag entscheidest du selbst: Du bestimmst, wann und auf welche Version du wechselst, kannst vorher testen und ein Backup ziehen. 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.

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:

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.

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.

bash
# 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
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. Ein Wechsel der PostgreSQL-Hauptversion hat seinen eigenen Rollback-Ablauf, siehe PostgreSQL 15 auf 18 aktualisieren.