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-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.