Micha/homelab-infra
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
8e820ea155fb2af2dcc7de9f4bd80c1ecebd2e81
homelab-infra/CLAUDE.md
T
Micha cd650b19ac Close Gitea signup, dedup posture-check alerts, extend Borg scope 
Operational hardening across several services after live incident
analysis between 2026-05-18 and 2026-05-20:

- Gitea: disable public registration and OpenID signup/signin to
  stop the external POST / 5xx bursts that triggered availability
  alerts. New repo-wide policy requires every productive
  Micha/homelab-infra Komodo stack to ship with an active
  Gitea->Komodo webhook on the current stack ID (documented in
  CLAUDE.md, AI_CONTEXT.md, WORKFLOW.md).
- posture-check: extract the Disk1 fstype check into its own
  function so the documented Disk1 NTFS exception no longer raises
  ntfy warnings, skip POSIX inode checks on NTFS, and dedup ntfy
  alerts via a fingerprint state file with ALERT_REPEAT_SECONDS
  (default 24h). Repeat-spam on the same cause now suppressed.
- docker-critical-events: parse the event JSON for container name,
  action, exit code and signal; drop `die exit=0` events (clean
  stops); ship a structured ntfy message instead of the raw event
  line.
- Borg UI: mount /mnt/user/services into the backup container as
  /local/services:ro and include homelab-infra, stacks and
  posture-check in all-important-sources.txt. RESTORE_MATRIX and
  DISASTER_RECOVERY updated accordingly.
- Unraid user scripts: document the new
  homelab-operations-report-daily cron job and the SMTP password
  file it expects on the host.
- MIGRATION_LOG: capture the four live events from this window -
  Gitea 5xx burst + signup closure, Komodo webhook reconciliation,
  posture-check host-version verification, Borg scope extension,
  and Traefik 5xx alert detuning.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-23 11:05:35 +02:00

130 lines
5.7 KiB
Markdown
Raw Blame History

# 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/REPO_MAP.md`
4. `docs/SERVICE_CATALOG.md`
5. 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.
Reference in New Issue View Git Blame Copy Permalink