Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

docs: introduce DECISIONS.md decision register, slim architecture master

Browse Source 
- new docs/DECISIONS.md (ADR-light): decisions migrated from master
  section 13, MASTER_TODO parked items, hardware inventory and audit
  restliste into one chronological register
- HOMELAB_ARCHITECTURE_MASTER_V2.md: section 13 replaced by pointer,
  section 9 condensed (502 -> 372 lines, target picture only)
- ROLLBACK.md: drop rollback recipes for already removed services
  (uptime-kuma, grafana/influx legacy, stirling/glance bootstrap notes)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Micha
2026-06-11 07:06:18 +02:00
parent c80b51f585
commit 513f41b852
3 changed files with 141 additions and 249 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ROLLBACK.md
+14 -63
View File
@@ -1,6 +1,10 @@
# Rollback Guide - Homelab
# 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.
---
@@ -72,59 +76,14 @@ Bei Problemen mit Borg UI oder Dump-Automatisierung:
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
## Monitoring-Stack 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:
`monitoring/` ist der einzige Observability-Stack. Bei Problemen:
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
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
---
@@ -132,19 +91,11 @@ Nach einem Deploy:
Bevorzugte Quellen:
- Borg-Restore
- erzeugte PostgreSQL-/MariaDB-Dumps
- bekannte Appdata-Snapshots
- 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/`
Beispiele:
```bash
cp -r /mnt/user/appdata/<service> /mnt/user/backup/
```
```bash
pg_dumpall > /mnt/user/backup/pg_dump_$(date +%Y%m%d).sql
```
Dienst-spezifische Restore-Quellen, Dumps und Smoke-Tests stehen in `docs/RESTORE_MATRIX.md`.
---