homelab-infra/docs/MIGRATION_LOG.md

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-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-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 bleiben bewusst ohne Digest-Pin; 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.