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

16 KiB
Raw Blame History

Migration Log - Homelab GitOps

Dieses Dokument ist nur noch ein historischer Verlauf. Der aktuelle operative Ablauf steht in docs/WORKFLOW.md, das Zielbild in HOMELAB_ARCHITECTURE_MASTER_V2.md.

Aktueller Endstand

  • Gitea Online ist der verbindliche Sollzustand.
  • Komodo ist der einzige produktive Stack-Manager.
  • Portainer CE ist entfernt.
  • Firefly, Firefly-Fints und Semaphore sind entfernt.
  • Borg UI ist produktiv, Dump-Automatisierung laeuft host-seitig und ein Restore-Smoke-Test wurde erfolgreich durchgefuehrt.
  • GitHub Desktop ist der bevorzugte lokale Workflow fuer Fetch, Pull, Commit und Push.
  • Mutable Image-Tags sind auf die aktuell laufenden Digests eingefroren.

Historische Meilensteine

2026-05-17 - Monitoring-Zielstack konsolidiert

  • monitoring/ als zentraler Observability-Zielstack fuer Prometheus, Loki, Promtail, Grafana, node-exporter, cAdvisor und InfluxDB 3 Core vorbereitet.
  • monitoring-grafana nutzt den Repo-Standard authelia@file,secure-headers@file und Secrets per Datei statt Klartext-Stack-ENV.
  • monitoring-influxdb3-core uebernimmt den LAN-only Writer-Endpunkt fuer Home Assistant (8181 via INFLUXDB_BIND_IP).
  • ops/loki und ops/grafana-influxdb sind abgeloeste Altstaende und bleiben nur als Rollback-/Migrationsreferenz im Repo.

2026-05-07 - Vaultwarden Restore-Test praktisch verifiziert

  • Erster echter Vaultwarden-Mini-Restore gegen das produktive Borg-Repo hetzner_borg_appdata_critical erfolgreich durchgefuehrt.
  • Restore lief isoliert nach /mnt/user/backups/restore-lab/vaultwarden, nicht gegen produktive Pfade.
  • Testinstanz restoretest-vaultwarden wurde lokal auf 127.0.0.1:18080 gestartet; HTTP 200 und Login-Seite wurden erfolgreich bestaetigt.
  • Report wurde unter /mnt/user/backups/restore-reports/vaultwarden-2026-05-07.md geschrieben.
  • Fuer den praktischen Restore-Pfad wurden zwei hostseitige Voraussetzungen sichtbar und umgesetzt:
    • known_hosts fuer das Hetzner-Ziel im borg-ui-Container
    • Host-Secret-Datei /mnt/user/appdata/secrets/borg_repo_passphrase.txt fuer kuenftige Restore-Tests
  • Testdaten unter /mnt/user/backups/restore-lab/vaultwarden/data wurden nach erfolgreichem Lauf wieder bereinigt.

2026-05-07 - Gitea Restore-Test praktisch verifiziert

  • Erster echter Gitea-Mini-Restore gegen das produktive Borg-Repo hetzner_borg_appdata_critical erfolgreich durchgefuehrt.
  • Restore lief isoliert nach /mnt/user/backups/restore-lab/gitea, nicht gegen produktive Pfade.
  • Testinstanz restoretest-gitea wurde lokal auf 127.0.0.1:13000 und 127.0.0.1:12222 gestartet.
  • HTTP 200, HTML-Titel und lokaler SSH-Port wurden erfolgreich bestaetigt.
  • Report wurde unter /mnt/user/backups/restore-reports/gitea-2026-05-07.md geschrieben.
  • Testdaten unter /mnt/user/backups/restore-lab/gitea/data wurden nach erfolgreichem Lauf wieder bereinigt.

2026-05-07 - Paperless Restore-Test praktisch verifiziert

  • Erster echter Paperless-Mini-Restore gegen das produktive Borg-Repo hetzner_borg_appdata_critical erfolgreich durchgefuehrt.
  • Restore umfasste sowohl die Dateipfade als auch postgresql17-paperless.dump aus dem Borg-Archiv.
  • Testinstanzen restoretest-paperless, restoretest-paperless-postgres und restoretest-paperless-redis liefen isoliert ohne Traefik.
  • Login-Seite war lokal auf 127.0.0.1:18120 erreichbar.
  • Der Dump-Import in Test-Postgres war erfolgreich; die Test-Datenbank enthielt 25 Dokumente.
  • Report wurde unter /mnt/user/backups/restore-reports/paperless-2026-05-07.md geschrieben.
  • Testdaten unter /mnt/user/backups/restore-lab/paperless wurden nach erfolgreichem Lauf wieder bereinigt.

2026-05-06 - Komodo Webhook Secret getrennt

  • KOMODO_WEBHOOK_SECRET von KOMODO_SECRET_KEY getrennt und als eigene Stack-ENV-Variable dokumentiert.
  • Gitea-Komodo-Webhooks mit bisherigem Core-Secret wurden auf den neuen KOMODO_WEBHOOK_SECRET umgestellt; bereits individuelle per-Stack-Webhook-Secrets wurden beibehalten.
  • Host-.env, persistente Komodo-Compose und Gitea-Webhooks wurden als ein gemeinsamer Runtime-Schritt behandelt, damit Auto-Deploys nicht auseinanderlaufen.
  • Ein stale Gitea-Webhook auf eine nicht mehr vorhandene Komodo-Stack-ID wurde deaktiviert, nicht geloescht.

2026-05-06 - Authelia GMX SMTP Notifier

  • Authelia-Notifier von Filesystem-Log auf GMX SMTP (submission://mail.gmx.net:587) umgestellt.
  • SMTP-Passwort bleibt ausserhalb des Repos unter /mnt/user/appdata/secrets/authelia_smtp_password.txt.
  • Authelia-Compose erhaelt explizite DNS-Server, weil der SMTP-Startup-Check externe Namen wie mail.gmx.net aufloesen muss.
  • Repo-Baseline und Host-Config muessen bei Auth-Aenderungen weiter bewusst gemerged und vor Restart validiert werden.

2026-05-06 - Hermes DR und Mail-Archiver Authelia

  • Hermes Agent in docs/RESTORE_MATRIX.md und docs/DISASTER_RECOVERY.md mit Restore-Pfaden, Secret-/ENV-Hinweisen und Smoke-Test ergaenzt.
  • Mail-Archiver Web-UI hinter authelia@file,secure-headers@file gelegt; App-eigene Auth bleibt als zweite Schutzschicht bestehen.
  • M10/Komodo blieb unveraendert.

2026-05-05 - N-Aufraeum-Sprint

  • Obsolete Compose-Top-Level-Felder version: "3.9" aus Immich, Mail Archiver und Paperless entfernt.
  • Leere env/domains.env.example und env/global.env.example mit nicht geheimen Beispielwerten gefuellt.
  • Veraltete .keep-Platzhalter aus Verzeichnissen mit echten Compose-/Repo-Inhalten sowie zwei reine Geister-Verzeichnisse (host-services/plex, infra/dns) entfernt.

2026-05-16 - Backup-Konsistenz und erster Hardening-Schnitt

  • SQLite-Dumps fuer Gitea, Vaultwarden, Uptime Kuma, Speedtest Tracker und Filebrowser werden containerseitig als *.sqlite.dump erzeugt und per Freshness-Check geprueft.
  • nextcloud.dump und die Nextcloud-Userdaten sind als Option A im Borg-Scope dokumentiert.
  • Filebrowser mountet keine breite /mnt/user/appdata-Flaeche mehr, sondern nur noch Documents, Photos, Projekte sowie eigenen App-State.
  • Authelia Argon2id-Parameter in der Repo-Baseline auf iterations: 3, memory: 65536, parallelism: 4 gesetzt; produktive Host-Config muss kontrolliert gemerged und mit Test-User validiert werden.
  • Redis-Caches wurden auf redis:7.4-alpine@sha256:... vereinheitlicht; Nextcloud wurde mit Registry-validiertem Digest gepinnt.
  • Eindeutig aufloesbare latest@sha256-Images wurden auf konkrete Tags umgestellt: Homepage v1.12.3, code-server 4.116.0, Filebrowser v2.63.2, Speedtest Tracker 1.13.12.

2026-05-05 - M3b versionierte App-Images digest-gepinnt

  • Versionierte Nicht-Komodo-Images fuer BentoPDF, Mealie, Paperless, Paperless-GPT, AdGuard Home, Grafana, InfluxDB 3 Core und Traefik auf die am Host laufenden, manifest-validierten Digests gepinnt.
  • nextcloud:33.0.2-apache wurde bewusst nicht in diesem Schritt gepinnt, weil der lokal gelistete Digest nicht als Registry-Manifest fuer tag@sha256 validierbar war.
  • Redis-Caches und Komodo/M10 blieben unveraendert.

2026-05-05 - M6/M7/M8 Doku-Konsolidierung

  • hermes.kaleschke.info als produktive Hermes-Dashboard-Route hinter Traefik + Authelia in Architektur, Repo-Map und Service-Katalog ergaenzt.
  • grafana und influxdb3-core laufen weiterhin als user: "0"; das wurde als Host-Appdata-Permissions-Ausnahme dokumentiert und nicht nebenbei geaendert.
  • Tailscale-Ausnahme um NET_ADMIN, NET_RAW und /dev/net/tun ergaenzt.
  • Komodo-Secret-/Webhook-Themen wurden bewusst nicht geaendert; Komodo-Aenderungen erfolgen nur gemeinsam mit dem Betreiber.

2026-05-05 - M3a stateful Digest-Pinning

  • PostgreSQL 17 Datenhalter auf postgres:17.9@sha256:5b96f1a16bd9768b060dd2ffe55cb6225c4d9ef4d214a8b21eb08134869a97e4 gepinnt (postgresql17, mealie-postgres, nextcloud-postgres).
  • Immich pgvector-Postgres auf tensorchord/pgvecto-rs:pg14-v0.2.0@sha256:739cdd626151ff1f796dc95a6591b55a714f341c737e27f045019ceabf8e8c52 gepinnt.
  • Komodo Mongo auf mongo:7.0.32@sha256:32979a1189dfdc44da3f5ed40d910495f5ad8f6f7f77556646f890a30b2d3f56 sowie Komodo Core/Periphery und Gitea auf die am Host laufenden Digests gepinnt.
  • Redis-Caches wurden am 2026-05-16 auf redis:7.4-alpine@sha256:... vereinheitlicht; Redeploys erfolgen stackweise mit Smoke-Test, nicht parallel.

2026-05-04 - Komodo Self-Stack Drift auf persistenten Pfad zurueckgefuehrt

  • Drift-Befund: komodo-core und komodo-periphery liefen aus /tmp/komodo-core-repair.yml bzw. /tmp/komodo-periphery-repair.yml; komodo-mongo verwies auf /mnt/user/services/stacks/komodo/compose.yaml, obwohl dieser Pfad fehlte.
  • Vor Eingriff wurden die Repair-Dateien und zugehoerigen /tmp/*.env-Dateien unter /mnt/user/appdata/komodo/_drift_backup_2026-05-04/ gesichert.
  • Zusaetzlich wurde eine geschuetzte Recovery-ENV unter /mnt/user/appdata/secrets/_komodo_stack_env_recovery_2026-05-04.env abgelegt; diese Datei enthaelt Tier-1-Secret-Material und ist kein Dauerzustand.
  • Vor dem Reconcile wurde das host-seitige Dump-Skript ausgefuehrt; komodo-mongo.archive.gz wurde frisch unter /mnt/user/backups/borg/dumps/latest/ erzeugt.
  • Persistenter Self-Stack wurde unter /mnt/user/services/stacks/komodo/compose.yaml aus ops/komodo/docker-compose.yml wiederhergestellt; .env wurde hostseitig aus der bestehenden Runtime-ENV abgeleitet.
  • Der vollstaendige Dry-run haette auch komodo-mongo recreated und wurde daher nicht ausgefuehrt. Stattdessen wurden nur komodo-core und komodo-periphery gezielt mit --no-deps --force-recreate aus dem persistenten Pfad neu erstellt; komodo-mongo blieb unveraendert healthy.
  • Smoke-Tests: docker compose ls zeigt fuer komodo nur noch /mnt/user/services/stacks/komodo/compose.yaml, Mongo pingt { ok: 1 }, https://komodo.kaleschke.info liefert HTTP 200, und Periphery meldet sich am Core an.
  • Die /tmp/*repair.yml-Dateien bleiben vorerst als Altlast erhalten und duerfen erst nach stabiler Laufzeit bewusst entfernt oder ins Drift-Backup verschoben werden.

2026-05-04 - Authelia ACL-Drift hostseitig gemerged

  • Die produktive Authelia-Config ist groesser als die Repo-Datei, weil sie hostseitige OIDC-/Secret-Konfiguration enthaelt. Die Repo-Datei wurde daher als nicht geheime Baseline eingeordnet und nicht blind auf den Host kopiert.
  • Host-Backup vor Aenderung: /mnt/user/appdata/authelia/config/configuration.yml.bak-20260504-acl-sync.
  • Minimaler Host-Merge: homepage.kaleschke.info wurde aus der bypass-Liste entfernt, komodo.kaleschke.info aus der 2FA-Liste entfernt, und default_redirection_url wurde auf https://home.kaleschke.info gesetzt.
  • authelia validate-config war erfolgreich; Authelia wurde neu gestartet und war danach healthy.
  • Smoke-Tests: home.kaleschke.info liefert fuer anonyme Requests eine Authelia-Weiterleitung, komodo.kaleschke.info bleibt ueber native Komodo-Auth erreichbar.

2026-05-04 - Home Assistant InfluxDB LAN-Port und Drift-Runbook

  • influxdb3-core fuer Home-Assistant-Writer auf LAN-Port 8181 vorbereitet und deployed.
  • InfluxDB bleibt ohne Traefik-/Public-Route und haengt nicht im frontend_net.
  • Fuer aktives Docker Host-Port-Publishing wurde zusaetzlich zum internen grafana_influx_internal das Compose-Netz grafana_influx_lan ergaenzt.
  • Komodo Periphery dauerhaft um /mnt/user/services:/mnt/user/services und frontend_net ergaenzt, damit Stack-Workspaces und Gitea-Zugriff reproduzierbar funktionieren.
  • docs/GITOPS_DRIFT_RUNBOOK.md angelegt, um lokale Git-Kopie, Gitea, Komodo Workspace, Docker Runtime und Host-Listener getrennt zu pruefen.

2026-03-28 - GitOps-Konsolidierung

  • Komodo als primaeren Stack-Manager eingefuehrt.
  • Portainer aus dem Zielbild herausgenommen.
  • Traefik auf 100% Docker-Labels konsolidiert.
  • diun entfernt; Update-Monitoring wird ueber Komodo abgedeckt.

2026-03-29 - Portainer abgeschaltet

  • Portainer CE aus dem produktiven Betrieb entfernt.
  • Komodo als alleinigen Stack-Manager festgezogen.

2026-04-13 bis 2026-04-15 - Borg-Rollout abgeschlossen

  • critical_infra erfolgreich nach Borg gesichert.
  • Pre-Backup-Dumps host-seitig ueber Unraid User Scripts etabliert.
  • Dump-Zielpfad auf /mnt/user/backups/borg/dumps umgestellt.
  • Restore-Smoke-Test fuer postgresql17-globals.sql und gitea.db erfolgreich nachgewiesen.
  • Monitoring fuer Borg ueber ntfy und Uptime Kuma eingerichtet.

2026-04-15 - Repo- und Betriebsbereinigung

  • Firefly, Firefly-Fints und Semaphore aus Repo und Homelab entfernt.
  • GitHub Desktop als Standard-Workflow fuer den lokalen Sync festgelegt.

2026-04-17 - Sicherheits- und Doku-Abgleich

  • code-server hinter authelia@file,secure-headers@file abgesichert.
  • Traefik-Dashboard von dashboard-auth@file auf authelia@file,secure-headers@file umgestellt; BasicAuth-Hash aus dem Repo entfernt.
  • Redis von Klartext in der Compose auf Secret-Datei unter /mnt/user/appdata/secrets/redis_password.txt umgestellt.
  • Redis-Passwort bewusst nicht rotiert; Live-Passwort bleibt vorerst unveraendert.
  • mail-archiver in der Architektur-Doku an den realen Traefik-Betrieb angepasst.
  • paperless-gpt von LOG_LEVEL=debug auf info umgestellt.
  • speedtest-tracker von APP_DEBUG=true auf false umgestellt.
  • Mutable Image-Tags fuer produktive Stacks auf die aktuell laufenden Digests eingefroren, um Deployments reproduzierbar zu machen.
  • paperless-ngx bleibt fuer PAPERLESS_DBPASS und PAPERLESS_REDIS vorerst bewusst bei Stack Environment Variables; keine Live-Migration auf _FILE, solange der aktuelle Stand stabil laeuft.
  • Disaster-Recovery-Runbook und Restore-Matrix fuer den Totalausfall-/Wiederanlauf-Fall neu dokumentiert.

2026-04-19 - paperless-gpt Digest-Pin zurueckgenommen

  • Der fuer paperless-gpt eingetragene Digest war syntaktisch ungueltig (63 statt 64 Hex-Zeichen) und wurde daher wieder auf icereed/paperless-gpt:latest zurueckgesetzt.
  • Diese Ruecknahme ist bewusst eng auf einen einzelnen defekten Pin begrenzt und aendert keine anderen Digest-Festschreibungen.
  • Die zwischenzeitlichen OCR-/Versions-Experimente fuer paperless-gpt wurden wieder auf den einfachen vorherigen Stand zurueckgenommen (icereed/paperless-gpt:latest, VISION_LLM_MODEL=cnshenyang/qwen3-nothink:14b), um den letzten bekannten Alltagszustand wiederherzustellen.

2026-04-19 - Nextcloud und Stirling-PDF vorbereitet

  • apps/nextcloud/docker-compose.yml als offizieller Docker-Microservice-Stack mit nextcloud:apache, eigener PostgreSQL-Datenbank und eigenem Redis vorbereitet.
  • Nextcloud folgt dem Repo-Standard frontend_net + app-internes Netz, nutzt _FILE-Secrets fuer Admin- und DB-Passwort und ist bewusst nicht hinter zentraler ForwardAuth, damit WebDAV/CardDAV und native Clients sauber funktionieren.
  • apps/stirling-pdf/docker-compose.yml als geschuetzter Tool-Stack hinter authelia@file,secure-headers@file vorbereitet.
  • Stirling-PDF nutzt persistente Pfade fuer /configs, /logs, /pipeline, /customFiles und /usr/share/tessdata; interne Stirling-Login-Funktion bleibt zugunsten des zentralen Traefik-/Authelia-Zugangs deaktiviert.

2026-04-30 - BentoPDF und Grafana/InfluxDB vorbereitet

  • stirling-pdf repo-seitig durch bentopdf ersetzt; Domain pdf.kaleschke.info bleibt erhalten.
  • BentoPDF laeuft als geschuetztes browserseitiges PDF-Tool hinter authelia@file,secure-headers@file und setzt zusaetzlich COOP/COEP-Header fuer SharedArrayBuffer-basierte Office-Konvertierung.
  • ops/grafana-influxdb als neuer Monitoring-Stack vorbereitet und spaeter in Betrieb genommen.
  • Grafana laeuft hinter Traefik + Authelia unter grafana.kaleschke.info.
  • InfluxDB 3 Core bleibt ohne Public Route und wird ueber eine provisionierte Grafana-Datenquelle angebunden.
  • Secrets fuer Grafana-Admin-Passwort, InfluxDB-Admin-Token und Grafana-Datasource-Token sind als Host-Dateien unter /mnt/user/appdata/secrets/ dokumentiert.

Dauerhafte Learnings

  • Kein Live-Editing in Komodo; Git gewinnt immer gegen manuelle Drift.
  • Webhooks koennen nach einem Push sofort einen Deploy ausloesen.
  • Rollback soll bevorzugt ueber saubere Git-Commits und bekannte Good States erfolgen, nicht ueber History-Rewrites auf master.
  • Doku soll Endzustaende beschreiben, nicht veraltete Zwischenstaende konservieren.
Reference in New Issue View Git Blame Copy Permalink