Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
b6bbca43add949b7795aa788d216aee10c88506c
homelab-infra/docs/ROLLBACK.md
T

5.8 KiB
Raw Blame History

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

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:

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
Reference in New Issue View Git Blame Copy Permalink