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. ops/grafana-influxdb in Komodo stoppen oder den letzten Git-Stand ohne diesen Stack deployen
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. bei Bedarf die abgeloesten Altstaende ops/loki und/oder ops/grafana-influxdb wieder starten
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

---

Daten-Rollback

Bevorzugte Quellen:

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

Beispiele:

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

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