Updates

Vesana aktualisiert sich über die Admin-UI. Der Updater-Sidecar führt das Update transaktional aus: Backup, Pull, Migration, Restart, Health-Check, bei Fehler automatischer Rollback.

Niemals manuell docker compose pull auf einer produktiven Instanz

Der GUI-Updater erstellt vor jedem Update einen Snapshot der Datenbank und der Compose-Datei. Manuelle Updates umgehen diesen Schutz und können den Stack in einen inkonsistenten Zustand bringen.

Online-Update (Standard)

Voraussetzungen: ausgehender Zugriff auf license.vesana.org (Update-Check) und ghcr.io (Image-Pull).

1. Admin → Updates öffnen
2. „Nach Updates suchen" klicken
3. Verfügbare Version + Changelog prüfen
4. „Jetzt updaten" klicken

Was im Hintergrund passiert:

sequenceDiagram
    participant UI as Admin-UI
    participant U as Updater-Sidecar
    participant LP as Licence-Portal
    participant R as Registry (ghcr.io)
    participant DB as Postgres

    UI->>U: Update auf vX.Y.Z starten
    U->>LP: latest-Manifest holen
    U->>DB: pg_dump + .env-Snapshot
    U->>LP: aktuelle docker-compose.prod.yml laden
    U->>R: docker compose pull
    U->>U: docker compose down api worker
    U->>DB: init-container: Migrations
    U->>U: docker compose up -d
    U->>U: Health-Check (90 s Timeout)
    U-->>UI: ✓ erfolgreich  (oder ✗ → Rollback)

Der gesamte Update-Lauf dauert typischerweise 1–3 Minuten. Während des Updates ist die UI für ~30 Sekunden nicht erreichbar (Container-Restart-Phase).

Offline-Update

Für Air-gapped-Umgebungen oder wenn der Server keinen direkten Zugriff auf ghcr.io hat.

Paket holen

Auf einem Rechner mit Internet:

• Variante A: Lizenzportal (license.vesana.org → Releases → Offline-Paket)
• Variante B: bestehende Online-Instanz: Admin → Updates → „Offline-Paket herunterladen"

Datei: vesana-update-vX.Y.Z.tar.gz. Inhalt: Docker-Image-Tarballs, Compose-File, Manifest, Migrations.

Paket einspielen

scp vesana-update-vX.Y.Z.tar.gz user@server:/opt/vesana/

Dann in der Admin-UI:

1. Admin → Updates → Offline-Paket hochladen
2. Datei auswählen → „Update starten"

Der Updater behandelt das Offline-Paket genauso wie ein Online-Update — Snapshot vorher, Migrations, Restart, Health-Check, Auto-Rollback bei Fehler.

Rollback

Wenn ein Update sichtbare Probleme verursacht:

1. Admin → Updates → Rollback
2. Zielversion aus den letzten Snapshots wählen (Default: vorletzte Version)
3. Bestätigen

Rollback spielt den DB-Snapshot zurück und startet die alten Image-Tags. Daten, die nach dem Update angekommen sind, gehen dabei verloren — daher ist der Rollback-Knopf in der UI bewusst klar gekennzeichnet.

Manueller Notfall-Pfad

Nur wenn die GUI nicht erreichbar ist und auch der Updater nicht antwortet:

cd /opt/vesana

# 1. Backup
docker compose -f docker-compose.prod.yml exec postgres \
  pg_dump -U vesana vesana | gzip > backup_$(date +%Y%m%d-%H%M%S).sql.gz

# 2. Compose-File aus dem Portal aktualisieren (nur falls vorgesehen)
sudo curl -sSL https://license.vesana.org/api/v1/install/compose -o docker-compose.prod.yml.new
diff docker-compose.prod.yml docker-compose.prod.yml.new
mv docker-compose.prod.yml.new docker-compose.prod.yml

# 3. Images aktualisieren
docker compose -f docker-compose.prod.yml pull

# 4. Init-Container für Migrations
docker compose -f docker-compose.prod.yml run --rm init

# 5. Stack neu starten
docker compose -f docker-compose.prod.yml up -d

Bei Offline-Update zusätzlich vor Schritt 3:

tar xzf vesana-update-vX.Y.Z.tar.gz -C /tmp/vesana-update
for img in /tmp/vesana-update/images/*.tar; do docker load < "$img"; done

Agent- und Collector-Updates

Agents und Collectors aktualisieren sich automatisch beim nächsten Config-Refresh (~5 Minuten Default-Intervall). Sie ziehen die aktuelle Version vom Server, prüfen die Signatur, ersetzen ihre eigene Binary und starten den Service neu.

Pause / Forcieren: siehe Agents & Collectors → Agent-Versionierung.

Versionierung

Vesana folgt Semver mit folgender Disziplin:

Sprung	Bedeutung
Patch (0.18.0 → 0.18.1)	Bug-Fixes, keine Schema-Änderungen, Rollback frei
Minor (0.18.x → 0.19.0)	Neue Features, additive Migrations, Rollback bedingt möglich
Major (0.x.y → 1.0.0)	Geplante Breaking Changes mit Migrations-Plan

Schema-Cleanups (DROP COLUMN/TABLE) folgen erst zwei Major-Releases nach dem Deprecation. Details zur Versionierungs-Politik: Changelog → Versionierung.

Anschluss

• Backup & Restore
• Troubleshooting