homelab-infra/docs/ROLLBACK.md

# Rollback Guide - Homelab

Dieses Dokument beschreibt den sicheren Rueckweg im aktuellen GitOps-Betrieb.

---

## 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

## BentoPDF / Stirling-PDF Rollback

Bei Problemen mit BentoPDF:

1. Git-Stand auf die letzte funktionierende Stirling-PDF-Compose zuruecknehmen oder gezielt `apps/bentopdf` wieder durch `apps/stirling-pdf` ersetzen
2. Commit + Push nach Gitea
3. betroffenen Stack in Komodo redeployen
4. `https://pdf.kaleschke.info` pruefen

Die alte Stirling-PDF-Persistenz unter `/mnt/user/appdata/stirling-pdf` nicht loeschen, solange der BentoPDF-Ersatz nicht fachlich abgenommen ist.

## Grafana / InfluxDB Rollback

Vor dem ersten produktiven Einsatz reicht es, den vorbereiteten Stack nicht zu deployen oder per Ruecknahme-Commit aus dem Repo zu entfernen.

Nach einem Deploy:

1. alten Grafana/InfluxDB-Stack in Komodo gestoppt lassen; der fruehere Compose-Pfad `ops/grafana-influxdb` ist seit 2026-05-26 nicht mehr im aktiven Repo
2. Persistenz unter `/mnt/user/appdata/grafana` und `/mnt/user/appdata/influxdb3` unangetastet lassen
3. Secrets unter `/mnt/user/appdata/secrets/grafana_admin_password.txt`, `/mnt/user/appdata/secrets/grafana_influxdb_token.txt` und `/mnt/user/appdata/secrets/influxdb3_admin_token.json` nur nach bewusstem Entscheid entfernen
4. Grafana-Domain und InfluxDB-Zugriff testen, bis klar ist, dass keine produktiven Dashboards oder Writer mehr davon abhaengen

## Monitoring-Zielstack Rollback

Der Zielzustand ist `monitoring/` als einziger Observability-Stack. Bei Problemen nach der Migration:

1. `monitoring` in Komodo stoppen oder auf den letzten funktionierenden Commit zurueckgehen
2. nur im echten Notfall die abgeloesten Altstaende aus der Git-Historie vor dem Repo-Cleanup wiederherstellen, z. B. aus Commit `ff5991c`; nicht dauerhaft parallel zum Zielstack betreiben
3. named volumes `prometheus_data`, `loki_data`, `promtail_positions`, `grafana_data` sowie `/mnt/user/appdata/influxdb3` nicht blind loeschen
4. Secrets `monitoring_grafana_admin_password.txt`, `monitoring_grafana_influxdb_token.txt` und `influxdb3_admin_token.json` nur nach bewusstem Entscheid entfernen
5. Home Assistant Writer erst wieder umstellen, wenn `curl -i http://192.168.178.58:8181/` erwartbar `401 Unauthorized` liefert
6. Grafana-Datasources `Prometheus`, `Loki` und `InfluxDB 3 Core` testen

## Uptime Kuma Removal Rollback

Falls die Blackbox-/Grafana-Ablösung unerwartet nicht ausreicht:

1. per Ruecknahme-Commit `ops/uptime-kuma/docker-compose.yml`, die Blackbox-/Glance-/Authelia-Referenzen und die Restore-Freshness-Pruefung auf den letzten Uptime-Kuma-Stand zurueckbringen
2. nach Gitea pushen und den Uptime-Kuma-Stack in Komodo neu anlegen oder aus dem letzten Stack-Backup wiederherstellen
3. `/mnt/user/appdata/_archive/uptime-kuma-removed-2026-05-25` nach `/mnt/user/appdata/uptime-kuma` zurueckverschieben, falls die Archivierung bereits erfolgt ist
4. `https://uptime.kaleschke.info` und die Monitore pruefen
5. erst danach den Blackbox-/Grafana-Zielzustand erneut bewerten

## Glance Dashboard Rollback

Vor dem ersten produktiven Einsatz reicht es, den vorbereiteten Stack `ops/glance` nicht zu deployen oder per Ruecknahme-Commit aus dem Repo zu entfernen.

Nach einem Deploy:

1. `glance` in Komodo stoppen oder auf den letzten funktionierenden Commit zurueckgehen
2. keine Produktivdaten loeschen; Glance nutzt nur Repo-Konfiguration und Stack-ENV
3. pruefen, ob `https://glance.kaleschke.info` nicht mehr geroutet wird oder wieder den erwarteten Stand zeigt
4. der `glance-docker-socket-proxy` darf nicht separat als Dauercontainer laufen bleiben

---

## Daten-Rollback

Bevorzugte Quellen:

- Borg-Restore
- erzeugte PostgreSQL-/MariaDB-Dumps
- bekannte Appdata-Snapshots

Beispiele:

```bash
cp -r /mnt/user/appdata/<service> /mnt/user/backup/
```

```bash
pg_dumpall > /mnt/user/backup/pg_dump_$(date +%Y%m%d).sql
```

---

## 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