Sicher auf FediSuite 2.0.0 upgraden

1. Ausgangslage und Wartungsfenster

Die Befehle unten führst du im Verzeichnis deiner Self-Hosting-Installation aus, also dort, wo docker-compose.yml und .env liegen. Verbinde dich per SSH mit deinem Server, wechsle in dieses Verzeichnis und prüfe mit pwd und ls -la, ob du richtig bist. Arbeite nicht in einer neu geklonten Kopie: Dort liegen deine Daten und Einstellungen nicht.

pwd
ls -la .env docker-compose.yml
docker compose ps
uname -m

Notiere dir den bisher genutzten Image-Tag und deine Anpassungen an der Compose-Datei. x86_64 steht üblicherweise für AMD64, aarch64 für ARM64. Plane ein Wartungsfenster: App und Worker werden neu erstellt und die Datenbankmigration kann bei vielen Konten einige Zeit brauchen.

Vorsicht bei latest: Die aktuelle Self-Hosting-Compose-Datei verwendet pull_policy: always. Schon ein späteres docker compose up -d kann damit ein neues Image holen. Führe vor dem Backup keine Compose-Startbefehle aus. Für ein kontrolliertes Upgrade empfehlen wir einen festen Tag.

Wenn deine Installation stark angepasst ist, vergleiche ihre Dienste, Volumes, Netzwerke und Proxy-Labels mit der aktuellen Compose-Vorlage. Überschreibe deine Datei nicht blind. Lies auch den Changelog, wenn du Versionen überspringst.

2. Backup vor dem ersten 2.0-Start

Ein laufender PostgreSQL-Datenordner lässt sich nicht zuverlässig mit cp oder tar sichern. Verwende für die Datenbank pg_dump. Stoppe zuerst App und Worker, damit während des Backups keine Beiträge oder Uploads geändert werden; die Datenbank bleibt für den Dump an. Das folgende Beispiel legt die Sicherung außerhalb des Git-Repositories in deinem Home-Verzeichnis ab. set -e beendet die Befehlsfolge bei einem Fehler.

set -e
umask 077
mkdir -p "$HOME/fedisuite-backups"
docker compose stop worker1 worker2 app
docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
  > "$HOME/fedisuite-backups/before-2.0.0.dump"
test -s "$HOME/fedisuite-backups/before-2.0.0.dump"
tar -czf "$HOME/fedisuite-backups/before-2.0.0-files.tar.gz" \
  .env docker-compose.yml uploads plugins logs

Falls eines der Verzeichnisse bei dir nicht existiert, passe die tar-Zeile an. Nutzt du benannte Docker-Volumes oder externe Speicher statt dieser Ordner, sichere deine tatsächlichen Speicherorte zusätzlich. Bewahre das Backup an einem zweiten, geschützten Ort auf und teste idealerweise eine Wiederherstellung. Der Dump kann noch unverschlüsselte Konto-Tokens enthalten; die .env enthält Passwörter. Behandle beides wie Secrets.

Wenn du vor dem ersten 2.0-Start abbrichst, kannst du die alten Container mit docker compose start app worker1 worker2 wieder starten. Mehr Details, inklusive Restore und Backup-Automatisierung, findest du unter Backup & Restore. Ein Datenbank-Dump ist auch dann nötig, wenn du zusätzlich einen Snapshot des ganzen Servers machst.

3. Eigenen Schlüssel erzeugen und sicher verwahren

Erzeuge einmalig einen zufälligen 32-Byte-Schlüssel. OpenSSL gibt dafür genau 64 hexadezimale Zeichen aus:

openssl rand -hex 32

Öffne die bereits vorhandene .env in einem Editor und ergänze eine Zeile. Ersetze den Platzhalter durch die gerade erzeugte Ausgabe. Kopiere nicht den Beispieltext und verwende auch nicht deinen JWT_SECRET:

ACCOUNT_ENCRYPTION_KEY=DEINE_64_HEX_ZEICHEN_HIER

Setze restriktive Rechte mit chmod 600 .env. Lege eine zusätzliche, verschlüsselte Sicherung dieses Schlüssels außerhalb des Servers an, etwa in deinem Passwortmanager. Gib ihn nicht in Tickets, Chat, Logs oder Git weiter. Ändere oder regeneriere ihn nach der Migration nicht. Auch spätere Backups brauchen genau den zum Datenbestand passenden Schlüssel.

Die App und alle Worker müssen denselben Wert sehen. Die aktuelle Compose-Vorlage lädt .env für app, worker1 und worker2 über env_file. Prüfe bei einer eigenen Compose-Datei diese drei Dienste und mögliche environment-Overrides. Gib zur Prüfung nicht docker compose config ohne --quiet aus: Die Ausgabe kann Secrets enthalten.

4. Compose-Datei und Dateirechte prüfen

Aktualisiere deine Self-Hosting-Compose-Datei anhand des Self-Hosting-Repositories. Ein git pull ist nur dann unkompliziert, wenn deine verfolgten Dateien unverändert sind. Bei eigenen Anpassungen: erst Unterschiede ansehen und dann gezielt übernehmen. Behalte deine vorhandene .env; ersetze sie nicht durch .env.example.

git status --short
# Nur wenn keine eigenen Änderungen an verfolgten Dateien vorliegen:
git pull --ff-only

Meldet git status Änderungen an docker-compose.yml oder schlägt git pull --ff-only fehl, nicht erzwingen. Vergleiche deine Datei mit der aktuellen Vorlage und übernimm die nötigen Änderungen manuell. Nutzt du gar keinen Git-Checkout, lade die neue Compose-Datei nicht einfach über deine angepasste Datei.

Prüfe insbesondere: env_file: .env bei App und allen Workern, die Bind Mounts für uploads, plugins und logs, und dieselbe Image-Variable für App und Worker. Für AMD64 setze in .env FEDISUITE_IMAGE=christinloehner/fedisuite:2.0.0; für ARM64 FEDISUITE_IMAGE=christinloehner/fedisuite:arm64-2.0.0.

Ab 2.0 läuft das Image ohne Root-Rechte mit UID/GID 1000:1000. Der Container muss in deine gemounteten Upload-, Plugin- und Log-Verzeichnisse schreiben können. Prüfe Eigentümer und Rechte:

stat -c '%u:%g %a %n' uploads plugins logs
docker compose config --quiet

Falls nötig, passe die Rechte dieser drei Verzeichnisse und ihres Inhalts nach dem Backup gezielt an UID 1000 an, zum Beispiel mit sudo chown -R 1000:1000 uploads plugins logs. Prüfe vorher, ob andere Dienste oder ACLs denselben Speicher nutzen. Ändere nicht pauschal den Besitzer des PostgreSQL-Datenordners und starte den FediSuite-Container nicht als Root.

5. Image laden, starten und Funktion prüfen

Erst jetzt, nachdem Dump, Dateien, Schlüssel und Compose-Datei geprüft sind, lädst du das neue Image und erstellst die Container neu:

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 app

Die App führt beim Start die Datenbankmigration aus und verschlüsselt vorhandene Zugangsdaten. Warte, bis app gesund ist; erst dann starten die abhängigen Worker. Bei vielen Konten kann das länger dauern. docker compose restart reicht für eine geänderte .env nicht, weil es die Container-Umgebung nicht neu einliest.

• Rufe deine Instanz im Browser auf und melde dich mit einem bestehenden Konto an.
• Prüfe, ob bisher verbundene Fediverse-Konten angezeigt werden und nutzbar sind. Teste nach Möglichkeit eine Aktion mit einem bestehenden Konto.
• Prüfe Uploads und gegebenenfalls installierte Plugins.
• Sieh mit docker compose logs --tail=100 worker1 worker2 nach Startfehlern; beide Worker sollten laufen.
• Beobachte die Instanz danach noch eine Weile auf Fehler. Sichere die aktualisierte .env mit dem Schlüssel erneut.

Dass der Login funktioniert, beweist nicht allein, dass die Konto-Verschlüsselung korrekt ist. Entscheidend sind ein erfolgreicher App-Start und die Funktion bereits verbundener Konten.

Wenn etwas schiefgeht

Ältere Datenbank-Backups und PostgreSQL-WAL-Dateien können weiterhin unverschlüsselte Tokens enthalten. Schütze sie entsprechend; das Upgrade verschlüsselt rückwirkend keine bereits angelegten Sicherungen.