# Domain Control aktualisieren

Die aktuelle Compose-Version ist `v1.5.0`. 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. Falls noch nicht geschehen, Gitea-Benutzername und das Passwort oder einen
   Token mit Lesezugriff auf Repository und Container-Paket 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.

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:

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

Danach im Ordner der Compose-Datei ausführen:

```bash
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:

```bash
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.0` 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:

```bash
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.