Vollständige Selfhost-Updates

scripts/selfhost-update.py ist der gemeinsame Update-Ablauf für die Kommandozeile und einen zukünftigen Update-Dienst. Diese Implementierung installiert noch keinen Dienst und stellt noch keinen Update-Button bereit. Der Prozess muss auf dem Docker-Host außerhalb der FEDEO-Container laufen.

Voraussetzungen und Umfang

Linux/amd64, Python ab 3.10, Docker Compose ab 2.24, tar und du.
Bestehendes Betriebsverzeichnis, standardmäßig /opt/fedeo, mit .env und docker-compose.yml; kein Git-Checkout.
Standard-Stack mit traefik, db, minio, createbuckets, backend, frontend und node-exporter. PostgreSQL und MinIO verwenden die lokalen Verzeichnisse postgres/ und minio/.
Als root auf dem Server ausführen: Docker-Zugriff und Leserechte für die Daten- und Zertifikatsverzeichnisse werden benötigt. Ein entfernter Docker-Daemon wird abgewiesen.
Die öffentliche HTTPS-Adresse muss vom Host erreichbar sein und ein gültiges Zertifikat haben.
Eine Wartungsunterbrechung für alle Mandanten einplanen. Vor dem Backup werden alle laufenden Dienste außer PostgreSQL angehalten, auch der öffentliche Proxy und alle im Backend laufenden Hintergrundaufgaben. Eine separate Wartungsseite folgt mit der späteren Oberflächenintegration.

Der Updater verweigert externe Datenbanken, externen S3-/Seafile-Speicher, zusätzliche Dienste, Compose-Profile, geänderte Datenpfade und PostgreSQL-Imagewechsel. Dafür braucht es zunächst passende Backup-/Migrationsadapter. Eigene Einstellungen innerhalb der unterstützten Dienste können in docker-compose.override.yml oder docker-compose.override.yaml bleiben; der Updater verwendet diese Datei bei jedem Compose-Aufruf. Änderungen an dieser Override-Datei werden nicht überschrieben.

Eine gezielte Ausnahme ist die Stilllegung des entfernten alten Matrix-Stacks: matrix-db, matrix-synapse, matrix-redis, matrix-element, matrix-livekit, matrix-rtc-jwt, matrix-turn und matrix-well-known dürfen in der bestehenden Konfiguration vorkommen. Die Zielkonfiguration muss ausschließlich die sieben FEDEO-Dienste enthalten, auch nach Zusammenführung mit einer Override-Datei. Matrix wird nicht in den neuen Stack übernommen. Andere Zusatzdienste bleiben gesperrt; die Fehlermeldung nennt die konkreten Abweichungen. Ein Abbruch mit mutationStarted: false und recoveryRequired: false benötigt keine Wiederherstellung und keinen resolve-Aufruf.

Für diesen Übergang müssen die Matrix-Daten lokal unter matrix/ liegen, insbesondere matrix/postgres und matrix/synapse; symbolische Links, andere konfigurierte Datenpfade, benannte Volumes und spezielle Compose-Konfigurationen benötigen eine manuelle Stilllegung. Die tatsächlichen Bind-Mounts der alten Container müssen zur Compose-Datei passen. Der Plan nennt retiredServices und retainedDataPaths und berücksichtigt den zusätzlichen Backup-Platz. Alle Matrix-Container werden vor dem Backup gestoppt. Das komplette lokale matrix/-Verzeichnis wird bei gestoppter Matrix-Datenbank in files.tar gesichert. Erst nach erfolgreichem Backup setzt der Updater die Neustartrichtlinie der alten Matrix-Container auf no, damit sie auch nach einem Host-Neustart stillgelegt bleiben. Er löscht weder diese Container noch ihre Daten oder Volumes. Image-seitig angelegte anonyme Volumes und schreibbare Container-Schichten bleiben an den alten Containern erhalten; sie sind nicht Bestandteil von files.tar. Die alten Container daher für die Wiederherstellung behalten und nicht mit --remove-orphans oder einem Docker-Prune entfernen.

Die Stilllegung vor der Dateisicherung entspricht den Anforderungen an ein PostgreSQL-Dateisystem-Backup; die Container-Richtlinie wird mit Docker update --restart geändert.

Die Zielversion muss bereits die festen MinIO-Digests und die neuen Backend-/Frontend-Healthchecks enthalten. Ältere Releases bleiben über den in docs/releases.md beschriebenen manuellen Ablauf installierbar. Ein Versionswechsel des Betriebssystems oder der Docker Engine gehört nicht zu diesem Ablauf.

Bereitstellung

Neue versionierte Installer laden das Skript und diese Anleitung bereits ins Betriebsverzeichnis und berücksichtigen Python 3 bei den Basispaketen. Bestehende Installationen können selfhost-update.py und SELFHOST-UPDATES.md aus den Assets eines entsprechenden veröffentlichten Releases übernehmen. Zuerst mit dessen SHA256SUMS prüfen, anschließend das Skript unter /opt/fedeo/scripts/selfhost-update.py ablegen. Für diese erstmalige Bereitstellung ist noch ein Serverzugriff erforderlich.

Ein bereits heruntergeladener Updater aus Release 3.1.0 enthält die Matrix-Stilllegung noch nicht. Dafür das Hostskript durch den korrigierten Stand aus einem neueren Release oder dem geprüften Repository-Commit ersetzen. Dieser kann weiterhin 3.1.0 als Zielrelease verwenden; dessen veröffentlichte Assets werden nicht verändert. Ein erneuter Download des alten 3.1.0-Updater-Assets liefert weiterhin den alten Stand. Der Updater ersetzt sich beim Anwenden nicht selbst.

Downloads erfolgen ausschließlich vom konfigurierten FEDEO-Repository über HTTPS. Die Dateiprüfsummen werden gegen SHA256SUMS, das Manifest gegen den Git-Tag geprüft. Die Prüfsummen sind keine unabhängige Signatur; das Vertrauen liegt beim Gitea-Server und dessen Release-Veröffentlichung. Falls das Repository privat ist, FEDEO_RELEASE_TOKEN mit Leserechten nur für den Aufruf setzen. Registry-Anmeldung bei Bedarf vorher über docker login git.federspiel.tech im Konto des Updaters durchführen. Der Updater speichert den Release-Token nicht in Statusdateien und gibt ihn bei Weiterleitungen an andere Hosts nicht weiter.

Prüfen, anwenden und Status lesen

Neueste stabile Version suchen oder eine bestimmte Version prüfen:

sudo python3 /opt/fedeo/scripts/selfhost-update.py check
sudo python3 /opt/fedeo/scripts/selfhost-update.py check --version 3.1.0

3.1.0 ist ein Beispiel und muss durch einen tatsächlich veröffentlichten Zielrelease ersetzt werden. Ein anderes Betriebsverzeichnis wird mit --directory /pfad/zur/instanz angegeben.

Die Prüfung lädt die Betriebsdateien und erstellt einen Plan einschließlich compose.diff und Release Notes unter /opt/fedeo/.updates/<Auftrag>/. Sie verändert die laufende Installation nicht und lädt noch keine Docker-Images. Die JSON-Ausgabe nennt Zielversion, Commit, betroffene Dienste, geschätzten Backup-Platz und die Pfade der Vorschau. Unveröffentlichte Entwürfe und Vorabversionen werden ignoriert.

Beim ersten Update kennt der Updater die Herkunft der vorhandenen Compose-Datei noch nicht. Die erzeugte compose.diff prüfen und eigene Anpassungen in die Override-Datei übertragen. Dann den Austausch ausdrücklich akzeptieren:

sudo python3 /opt/fedeo/scripts/selfhost-update.py apply --version 3.1.0 --accept-compose-replacement

Für spätere Updates unveränderter, vom Updater verwalteter Compose-Dateien:

sudo python3 /opt/fedeo/scripts/selfhost-update.py apply --version 3.2.0
sudo python3 /opt/fedeo/scripts/selfhost-update.py status

Eine explizite Zielversion ist beim Anwenden erforderlich. apply prüft die Release-Dateien und die tatsächliche Installation nochmals. Bei gleichen oder älteren stabilen Zielversionen wird abgebrochen. Änderungen an .env, Basis-Compose oder der Override-Datei während des Downloads führen ebenfalls vor der Wartungsphase zum Abbruch.

Während des ersten Ausbaus den Befehl in einer bestehenden persistenten Terminalsitzung ausführen. Der spätere Host-Dienst übernimmt die vom Browser unabhängige Ausführung. Ein Neustart des FEDEO-Stacks beendet diesen Host-Prozess nicht; ein Neustart des Hosts unterbricht ihn.

Ablauf und Speicherung

Exklusive Host-Sperre erwerben; offene Wiederherstellungsfälle blockieren neue Updates.
Release samt Prüfsummen laden, Manifest/Commit prüfen und die FEDEO-Images auf die exakten Digests setzen.
Aktuelle und neue Compose-Konfiguration mit Docker Compose validieren. Projektname, Container-Identitäten, Mounts, Netzwerke und Zugangsdaten erhalten. Die Shell-Umgebung überschreibt dabei keine Werte aus der Instanz-.env.
Speicherplatz prüfen: mindestens 5 GiB frei am Docker-Datenverzeichnis vor dem Pull sowie geschätzte Backup-Größe plus Reserve im Betriebsverzeichnis. Images laden, Backup-Platz erneut prüfen.
Schreibende Dienste und Proxy anhalten. PostgreSQL bleibt für pg_dump aktiv.
Konfiguration, Container-Metadaten, PostgreSQL-Dump im Custom-Format, globale PostgreSQL-Rollen, gestoppten MinIO-Dateispeicher und Zertifikate sichern. Dump und TAR auf Lesbarkeit prüfen und SHA-256-Prüfsummen schreiben. backup/complete.json markiert ein vollständig geschriebenes Backup; ein Restore-Probelauf auf einer getrennten Instanz wird dadurch nicht ersetzt. Beim Übergang vom alten Matrix-Stack enthält das TAR zusätzlich matrix/. Container-Metadaten enthalten die ursprünglichen Image-IDs, Mounts und Neustartrichtlinien; complete.json nennt die stillgelegten Dienste und erhaltenen Container. Vor dem Dateiaustausch wird deren automatischer Neustart deaktiviert. Das Zielrelease enthält keine Matrix-Dienste und keine Backend-Abhängigkeit auf Synapse mehr.
Compose-Datei und .env einzeln atomar ersetzen. In .env wird ausschließlich FEDEO_VERSION verändert; .env.example und Setup-Skript werden erneuert. Den laufenden Updater ersetzt dieser Vorgang nicht.
Infrastruktur starten, Bucket-Einrichtung ausführen und Migrationen explizit in einem benannten Einmalcontainer starten. Beim anschließenden regulären Backend-Start läuft dessen bestehende Migrationsprüfung nochmals; bereits angewendete Migrationen werden dabei übersprungen.
Stack mit up --wait starten. Backend-/Frontend-Image-IDs und Healthchecks sowie öffentlich gemeldete Version und Commit prüfen. Erst dann den Release als installiert speichern.

Status und Phasen werden atomar in .updates/status.json und pro Auftrag in status.json gespeichert. events.jsonl enthält den Verlauf, commands.log Fehlermeldungen der Werkzeuge. Das Verzeichnis hat Modus 0700; Status- und Konfigurationsdateien werden mit 0600 angelegt. Backups und Werkzeugausgaben enthalten vertrauliche Daten und dürfen nicht ungefiltert an eine Oberfläche ausgeliefert werden. Backups werden nicht automatisch gelöscht.

Fehler und Wiederherstellung

Download, Konfiguration oder Pull fehlgeschlagen: Der laufende Stack bleibt bestehen.
Backup oder Stop fehlgeschlagen: Der Updater versucht, die zuvor laufenden Container wieder zu starten. Gelingt das nicht, bleibt der Wiederherstellungsstatus gesetzt.
Ab Austausch der Dateien/Infrastruktur: Keine automatische Rückkehr zu älteren Images. Bei einem Fehler werden Backend, Frontend und Proxy nach Möglichkeit angehalten. Das Datenbankschema oder das Speicherformat könnten bereits verändert sein.
Prozess hart beendet oder Host neu gestartet: status erkennt einen zurückgelassenen laufenden Auftrag als interrupted. Eine vor Beginn der Wartung gespeicherte Wiederherstellungssperre bleibt erhalten. Abgeschlossene Teiloperationen werden nicht als erfolgreiches Update ausgegeben.

Zur Diagnose status und die geschützten Auftragsdateien lesen. Falls ein benannter fedeo-update-<Auftrag>-Migrationscontainer zurückgeblieben ist, dessen Zustand und Logs zuerst prüfen. Er kann unabhängig vom abgebrochenen Compose-Prozess weiterlaufen; erst nach geklärtem Zustand anhalten/entfernen.

Für die Rückkehr zum alten Stand in einem geplanten Wartungsfenster:

Alle schreibenden Dienste und den Proxy angehalten lassen; keinen neuen Update-Auftrag starten.
Prüfsummen aus backup/complete.json prüfen. Ursprüngliche Compose-Datei, .env und gegebenenfalls Override aus backup/config/ wiederherstellen. backup/containers.json dokumentiert die ursprünglichen Image-IDs; insbesondere bewegliche Infrastruktur-Tags vor dem Start auf die gesicherten Image-Stände festlegen.
Falls Migrationen/Infrastrukturänderungen bereits begonnen haben: PostgreSQL und Dateispeicher aus dem zusammengehörigen Backup wiederherstellen. Der PostgreSQL-Dump ist für pg_restore geeignet; globals.sql enthält Rollen und Kennwörter und muss beim Wiederaufbau der Datenbank berücksichtigt werden. MinIO und Zertifikate bei gestoppten Diensten aus files.tar wiederherstellen. Die konkrete Rücksicherung bestehender Daten erfolgt bewusst manuell und ersetzt Daten.
Wiederhergestellten Stack mit dessen Compose-Dateien starten und Funktionen prüfen. Alternativ den Fehler der Zielversion beheben und diese erfolgreich starten.
Erst nach erfolgreicher Wiederherstellung die Sperre aufheben:

sudo python3 /opt/fedeo/scripts/selfhost-update.py resolve --version 3.0.0

Bei Rückkehr zum alten Matrix-Stack dessen ursprüngliche Compose-Datei aus demselben Backup verwenden. Falls nötig, das vollständige matrix/-Verzeichnis aus files.tar bei gestoppten Matrix-Diensten wiederherstellen, insbesondere den gesamten PostgreSQL-Cluster mit dem ursprünglichen Datenbank-Image. Vorhandene Container-Schichten und anonyme Volumes bleiben an den behaltenen Containern erhalten. Für jeden betroffenen Container die ursprüngliche HostConfig.RestartPolicy aus backup/containers.json wieder setzen, beispielsweise docker update --restart=unless-stopped CONTAINER_ID, wenn genau diese Richtlinie gespeichert wurde. Danach die zuvor laufenden Matrix-Dienste mit der ursprünglichen Compose-Konfiguration starten und prüfen. resolve für den alten Stand prüft auch deren Image, Laufzustand und Neustartrichtlinie. resolve für den Zielrelease verlangt weiterhin gestoppte Matrix-Container mit deaktiviertem automatischem Neustart. Es führt diese Schritte nicht selbst aus.

resolve prüft die angegebene Backend-Version, Backend-Erreichbarkeit, Frontend-Erreichbarkeit, laufende Kerndienste, passende Anwendungs-Images und das Fehlen eines zurückgebliebenen Migrationscontainers. Es stellt selbst keine Daten wieder her. Bei alten Entwicklungsinstallationen die tatsächlich von /backend/version gemeldete Entwicklungsversion angeben. Ein späteres Update kann nach einer manuellen Compose-Wiederherstellung erneut --accept-compose-replacement erfordern.

Entwicklung und Tests

npm test
npm run commits:check

Die Update-Tests verwenden den echten Compose-Parser und einen simulierten Docker-Daemon. Sie prüfen u. a. Erfolg, Prüfsummen, Release-Auswahl, unveränderte Konfiguration, Speicherplatz, parallele Aufträge, Backupfehler, Migrationsfehler, falsche laufende Versionen und unterbrochene Aufträge. Die Matrix-Tests prüfen Stilllegung, Daten-/Container-Erhalt, Backup vor Änderung der Neustartrichtlinien, Fehler und Unterbrechungen sowie die weitere Ablehnung unbekannter Dienste. Ein vollständiger Test mit realem PostgreSQL-/MinIO-/Matrix-Restore auf einer separaten Selfhost-Testinstanz ist vor dem Produktionseinsatz zusätzlich erforderlich.

15 KiB Raw Blame History