homelab-infra/CLAUDE.md

Claude Code Context - Homelab Infra

Stand: 2026-05-04

Dieses Repository ist die GitOps-Quelle fuer das KalliLab CORE Homelab auf einem Unraid-Host. Es verwaltet Docker-Compose-Stacks fuer Core-Dienste, Security, Infrastruktur, Apps, Operations-Tools, Host-nahe Dienste und Traefik. Gitea Online ist die operative Quelle der Wahrheit; Komodo konsumiert den Git-Stand und deployed daraus.

Vor jeder Aenderung lesen

Claude muss vor jeder fachlichen oder technischen Aenderung mindestens diese Dateien lesen:

1. HOMELAB_ARCHITECTURE_MASTER_V2.md
2. docs/WORKFLOW.md
3. docs/README.md
4. docs/REPO_MAP.md
5. docs/SERVICE_CATALOG.md
6. die betroffene docker-compose.yml

Zusaetzlich je nach Thema:

• Restore / Host-Ausfall: docs/DISASTER_RECOVERY.md und docs/RESTORE_MATRIX.md
• Rollback: docs/ROLLBACK.md
• Secrets: docs/SECRETS_MAP.md
• GitOps-/Komodo-/Runtime-Drift: docs/GITOPS_DRIFT_RUNBOOK.md
• Gesamtbild fuer KI-Agenten: docs/AI_CONTEXT.md
• Home Assistant / Ecowitt / InfluxDB: docs/HOME_ASSISTANT_INFLUXDB_ECOWITT.md

Projektbeschreibung

• Host: Unraid, Hostname Kallilabcore
• Domain: kaleschke.info
• Reverse Proxy: Traefik v3
• DNS: AdGuard Home + Unbound
• VPN/Remote: Tailscale
• Git: Gitea unter git.kaleschke.info
• Deployment: Komodo als primaerer und einziger produktiver Stack-Manager
• Lokale Arbeitskopie: Windows/GitHub Desktop
• Persistenz: ueberwiegend /mnt/user/appdata, Nutzdaten in /mnt/user/documents, /mnt/user/photos, GitOps/Gitea in /mnt/user/services

Architekturprinzipien

• Traefik ist der einzige oeffentliche HTTP(S)-Einstiegspunkt.
• Service-Routing erfolgt per Docker-Labels, nicht ueber neue Traefik File-Provider-Service-Routen.
• frontend_net ist das Web-/Proxy-Netz.
• backend_net ist internal: true fuer Datenbanken, Redis und interne Backends.
• App-interne Netze sind erlaubt, wenn sie eine App und ihre Datenbank/Worker sauber isolieren.
• Datenbanken und Caches duerfen nicht im frontend_net liegen.
• Direkte Host-Ports sind nur mit dokumentierter Ausnahme erlaubt.
• Komodo bleibt bewusst ohne pauschale zentrale Authelia-ForwardAuth-Middleware.
• Secrets gehoeren niemals ins Git-Repository.
• Produktive Container sollen als Compose/Git-Stack verwaltet werden.

GitOps-Regeln

Quelle der Wahrheit:

1. Gitea origin/master
2. lokaler Clone
3. Komodo Stack Workspace
4. laufende Docker-Container
5. Host-Zustand

Standard-Workflow:

1. Lokal synchronisieren (Fetch, ggf. Pull)
2. Betroffene Docs und Compose-Datei lesen
3. Zielzustand und Rollback klaeren
4. Lokal minimal aendern
5. Validieren
6. Commit und Push durch den Benutzer oder nach expliziter Freigabe
7. Komodo-Deploy/Runtime pruefen
8. Dokumentation nachziehen

Neue produktive Komodo-Stacks aus Micha/homelab-infra brauchen verpflichtend einen aktiven Gitea->Komodo-Webhook auf die aktuelle Stack-ID. Ausnahmen muessen im selben Aenderungsblock dokumentiert werden.

Wenn Drift vermutet wird, nicht raten. Erst die Pflichtmatrix in docs/GITOPS_DRIFT_RUNBOOK.md abarbeiten.

Sicherheitsregeln

• Secret-Werte niemals ausgeben. Wenn Werte auftauchen: redakten.
• Nur Secret-Namen, Env-Key-Namen und Pfade dokumentieren.
• Keine produktiven .env- oder Stack-Env-Werte zitieren.
• Keine Compose-Aenderung ohne vorherigen Architektur-/Workflow-Abgleich.
• Keine Deployments, Host-Hotfixes oder Docker-Schreibbefehle ohne ausdrueckliche Anweisung.
• Keine direkten Host-Ports fuer Web-UIs, ausser dokumentierte Ausnahmen.
• privileged: true, Docker-Socket und Host-Netz nur als dokumentierte Ausnahme.
• Traefik dynamic config unter traefik/dynamic/ wird nicht automatisch von Komodo deployed und muss bei Aenderungen manuell auf den Host synchronisiert werden.

Bekannte dokumentierte Ausnahmen

• traefik: Host-Ports 80/443
• gitea: SSH-Port 222
• AdGuard Home: DNS-Port 53 und LAN-Admin-Port 8082
• tailscale: network_mode: host
• Plex-Media-Server: historischer Host-Netz-Sonderfall, nicht als Repo-Stack enthalten
• scrutiny: privileged: true fuer SMART/Laufwerkszugriff
• Komodo: Docker-Socket und native Auth ohne pauschale ForwardAuth
• traefik/dynamic/*: manuelle Host-Sync-Ausnahme
• influxdb3-core: LAN-only Host-Port 8181 fuer Home Assistant Writer, keine Traefik-Route, nicht im frontend_net

No-Go-Regeln

• Keine produktiven Aenderungen direkt in Komodo.
• Keine docker run-Ad-hoc-Container als Dauerzustand.
• Keine Compose-Dateien, Secrets oder Host-Konfigurationen stillschweigend aendern.
• Keine Deployments ausloesen, wenn der Benutzer nur Analyse oder Dokumentation verlangt.
• Kein push --force auf master als Standard-Rollback.
• Keine History-Rewrites ohne ausdrueckliche Freigabe.
• Keine Loesch-, Reset- oder Migrationsbefehle ohne klaren Zielzustand und Rollback.
• Keine neuen latest-/mutable Image-Tags ohne bewusste Versionsentscheidung.

Rollback-Erwartungen

Jede Aenderung braucht vor dem Deploy eine klare Rueckkehrstrategie:

• letzter bekannter funktionierender Git-Stand
• betroffener Stack und Persistenzpfade
• ob Datenpfade unveraendert bleiben
• ob Secrets/ENV betroffen sind
• konkrete Smoke-Tests nach Rollback

Standard-Rollback ist ein Ruecknahme-Commit oder gezielte Rueckaenderung mit Push nach Gitea. Produktive Datenpfade unter /mnt/user/appdata, /mnt/user/documents, /mnt/user/photos, /mnt/user/services und /mnt/user/backups nicht blind loeschen.

Arbeitsweise fuer Claude

• Erst lesen, dann handeln.
• Bei Unsicherheit Zustand messen, nicht erraten.
• Aenderungen klein halten und nur den betroffenen Bereich anfassen.
• Bestehende Doku und Repo-Konventionen bevorzugen.
• Bei Secret-/Runtime-/Komodo-Fragen besonders konservativ sein.
• Wenn zwei Reparaturversuche nicht funktionieren: stoppen, Pflichtmatrix ausfuellen, eine abweichende Ebene benennen.