hetzner-api-dyndns-records-webinterface/UPDATE.md

Domain Control aktualisieren

Die aktuelle Compose-Version ist v1.5.2. Datenbank, Einstellungen und verschlüsselte API-Zugänge liegen in benannten Docker-Volumes und bleiben bei den folgenden Verfahren erhalten.

Direkt in der Weboberfläche

1. Als Administrator anmelden und Update öffnen.
2. Bei öffentlichen Releases und Images ist keine Anmeldung erforderlich. Für private Repositories oder Container-Pakete Gitea-Benutzername und Passwort oder einen Token mit den entsprechenden Leserechten hinterlegen.
3. Nach Update suchen und anschließend Jetzt aktualisieren wählen.
4. Warten, bis Image-Download, Containerwechsel und Healthcheck abgeschlossen sind. Bei einem Fehler versucht der Update-Agent automatisch, den vorherigen Container wiederherzustellen.

Die Wiederherstellung greift auch dann, wenn Docker den bisherigen Container bereits gestoppt hat, aber die Antwort auf den Stopp-Aufruf verloren geht. Healthcheck-Zeitlimits schließen blockierte Docker-Anfragen ein.

Jede Release-Prüfung und jeder Image-Download beginnt ohne Anmeldung. Nur bei fehlendem Zugriff werden gespeicherte Zugangsdaten verwendet. Der Wechsel zwischen öffentlich und privat wird bei jedem Vorgang erneut berücksichtigt; die Sichtbarkeit des Git-Repositories und des Container-Pakets wird getrennt geprüft. Ein nicht sichtbares Release (HTTP 404) kann auch bedeuten, dass noch kein Release veröffentlicht wurde.

Ältere Update-Agenten mit Protokoll 2 verlangen noch Zugangsdaten. Für anonyme Image-Downloads muss der Agent einmal gemeinsam mit der Web-App per Compose auf eine Version mit dieser Funktion aktualisiert werden. Die Web-App erkennt diese Fähigkeit im Agent-Status; die bestehenden Kompatibilitätsgrenzen bleiben erhalten. Mit gespeichertem Zugang bleiben ältere kompatible Agenten nutzbar.

Ein nicht erreichbarer Git- oder Registry-Server unterbricht den laufenden DynDNS-Dienst nicht. Direkte Sprünge über mehrere Versionen sind möglich, wenn das Ziel-Image die laufende Version ausdrücklich unterstützt. Diese Kompatibilität wird nach dem Download und vor dem ersten Containerwechsel geprüft. Ein inkompatibles Release wird ohne Unterbrechung abgelehnt.

Nach einem Neustart des Docker-Hosts prüft die Web-App den Update-Agenten mit kurzem Abstand erneut. Der Update-Klick führt zusätzlich immer eine aktuelle Prüfung durch und wartet bei Bedarf darauf, dass der Container seinen Start-Healthcheck beendet. Ein separater manueller Neustart der Anwendung ist dafür nicht mehr erforderlich.

Über Container neu starten auf der Update-Seite lässt sich der vollständige Anwendungscontainer außerdem gezielt neu starten. Datenbank, Secrets und Einstellungen bleiben erhalten. Diese Funktion setzt die im mitgelieferten Compose konfigurierte Richtlinie restart: unless-stopped voraus.

Die sichere Update-Basis beginnt mit v1.4.0. Installationen bis einschließlich v1.3.0 werden einmalig wie unten beschrieben mit Compose aktualisiert. Danach kann der Agent auch dann weitere kompatible Releases installieren, wenn seine eigene Versionsnummer älter als die der Web-App ist. Erscheint Compose aktualisieren, benötigt das Ziel einen neueren Agent-Vertrag; dann beide Container wie unten beschrieben gemeinsam aktualisieren.

Mit Docker Compose

In compose.yml wird nur die zentrale, konkret gepinnte Image-Zeile geändert:

services:
  dyndns:
    image: &image git.j-mahler.de/admin/domain-control-webinterface-prod:v1.5.2
  update-agent:
    image: *image

Danach im Ordner der Compose-Datei ausführen:

docker compose pull
docker compose up -d --force-recreate
docker compose ps

Die Web-App und der Update-Agent verwenden durch den YAML-Anker dieselbe Version. Für das Update ist kein docker compose down nötig. Insbesondere niemals docker compose down -v verwenden, da -v die Daten- und Secret-Volumes löschen würde.

Der Ein-Klick-Updater kann die auf dem Host liegende compose.yml nicht verändern. Vor jedem späteren manuellen Compose-Lauf daher zuerst den gepinnten Tag auf die gewünschte Version setzen, damit Compose keine ältere Version wiederherstellt.

Der Healthcheck lässt sich anschließend direkt prüfen:

curl --fail http://127.0.0.1:9090/healthz

Die erwartete Antwort lautet ok.

Portainer oder Dockge

1. Den bestehenden Stack bearbeiten.
2. Nur den Tag der zentralen Image-Zeile auf v1.5.2 setzen.
3. Den Stack mit vorherigem Image-Pull erneut bereitstellen.
4. Kontrollieren, dass beide Container laufen und die Web-App healthy ist.

Den Stack nicht mitsamt seinen Volumes löschen oder neu anlegen.

Rollback

Falls ein manuelles Rollback nötig ist, die zentrale Image-Zeile wieder auf die zuvor eingesetzte konkrete Version setzen und erneut ausführen:

docker compose pull
docker compose up -d --force-recreate

Vor größeren Versionssprüngen sollten die Volumes dyndns-data und dyndns-secrets gemeinsam gesichert werden. Nur zusammen enthalten sie sowohl die Datenbank als auch den zur Entschlüsselung benötigten Master-Key.