# Rollback Guide - Homelab

Typ: Runbook · Stand: 2026-06-11 · Status: aktiv

Dieses Dokument beschreibt den sicheren Rueckweg im aktuellen GitOps-Betrieb.
Rollback-Anleitungen fuer bereits entfernte Dienste (Uptime-Kuma, Grafana-/
InfluxDB-Altstack, Stirling-PDF) liegen in der Git-Historie, nicht mehr hier.

---

## Grundprinzip

Rollback bedeutet in diesem Setup:

- auf einen bekannten funktionierenden Git-Stand zurueckgehen
- den Zustand sauber nach Gitea bringen
- Komodo gezielt auf diesen Stand deployen lassen

`master` wird dabei **nicht** per `push --force` umgeschrieben, solange es keinen ausdruecklich abgestimmten Ausnahmefall gibt.

---

## Standard-Rollback ueber Git

Bevorzugter Weg:

1. den letzten funktionierenden Commit identifizieren
2. lokal einen sauberen Ruecknahme-Commit erzeugen (`git revert` oder gezielte Rueckaenderung)
3. nach Gitea pushen
4. Komodo-Deploy und Funktion pruefen

Warum so:

- die Historie bleibt nachvollziehbar
- Webhooks und Team-Workflow bleiben stabil
- es gibt keinen verdeckten History-Rewrite auf `master`

---

## Rollback ueber Komodo

Komodo ist der operative Deploy-Consumer, nicht die Quelle der Wahrheit.

Vorgehen:

1. Git-Stand in Gitea auf den gewuenschten Sollzustand bringen
2. betroffenen Stack in Komodo oeffnen
3. Redeploy auf Basis dieses Git-Stands ausloesen
4. Logs, Health und Erreichbarkeit pruefen

Wichtig:

- kein manuelles Ueberschreiben im Komodo-Web-Editor
- wenn Komodo und Git abweichen, gewinnt Git

---

## Ausnahmefall: harter Git-Rollback

Ein `git reset --hard` mit anschliessendem erzwungenem Push auf `master` ist **kein Standardverfahren**.

Das kommt nur in Frage, wenn:

- der Fall bewusst abgestimmt ist
- klar ist, welche Webhook-/Deploy-Seiteneffekte ausgeloest werden
- keine sauberere Ruecknahme ueber `git revert` mehr sinnvoll ist

---

## Borg / Backup-bezogener Rollback

Bei Problemen mit Borg UI oder Dump-Automatisierung:

1. auf den letzten funktionierenden Git-Stand zurueckgehen
2. `borg-ui` ueber Komodo redeployen
3. Persistenz unter `/mnt/user/appdata/borg-ui/` und `/mnt/user/backups/borg/dumps/` nicht blind loeschen
4. Restore zuerst in einen Testpfad schreiben, nicht direkt in Produktivpfade

## Monitoring-Stack Rollback

`monitoring/` ist der einzige Observability-Stack. Bei Problemen:

1. `monitoring` in Komodo stoppen oder auf den letzten funktionierenden Commit zurueckgehen
2. named volumes `prometheus_data`, `loki_data`, `promtail_positions`, `grafana_data` sowie `/mnt/user/appdata/influxdb3` nicht blind loeschen
3. Secrets (`monitoring_grafana_admin_password.txt`, `monitoring_grafana_influxdb_token.txt`, `influxdb3_admin_token.json`) nur nach bewusstem Entscheid entfernen
4. Grafana-Datasources `Prometheus`, `Loki` und `InfluxDB 3 Core` testen

---

## Daten-Rollback

Bevorzugte Quellen:

- Borg-Restore (zuerst in Testpfade unter `/mnt/user/backups/restore-lab/`)
- erzeugte Dumps unter `/mnt/user/backups/borg/dumps/latest`
- bekannte Appdata-Archivstaende unter `/mnt/user/appdata/_archive/`

Dienst-spezifische Restore-Quellen, Dumps und Smoke-Tests stehen in `docs/RESTORE_MATRIX.md`.

---

## Betriebsregeln

- immer nur eine aenderungsrelevante Massnahme gleichzeitig
- vor jedem Rollback pruefen, ob ein aktuelles Backup existiert
- nach jedem Rollback Funktion, Logs und Erreichbarkeit pruefen
- wenn etwas unklar ist: stoppen, Zustand analysieren, dann gezielt eingreifen