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.