Claude ready

Claude ready

docs/AI_CONTEXT.md

@@ -0,0 +1,175 @@
+# AI Context
+
+Stand: 2026-05-04
+
+Diese Datei ist fuer KI-Agenten gedacht, die das Homelab-Repo schnell verstehen muessen. Sie ersetzt nicht die Detaildokumente, sondern fasst Zielbild, Betriebsmodell und Risiken zusammen.
+
+## Kurzfassung
+
+Dieses Repository beschreibt ein Unraid-basiertes Homelab namens `Kallilabcore`. Der Betrieb folgt GitOps: Gitea `origin/master` ist die Quelle der Wahrheit, der lokale Clone ist Arbeitskopie, Komodo deployed aus Gitea, Docker Runtime und Host sind Ergebnis, nicht Bearbeitungsort.
+
+Traefik ist der zentrale Web-Einstieg fuer HTTP(S). Admin-/Ops-UIs liegen entweder hinter Authelia/secure headers oder sind als Ausnahme dokumentiert. Secrets liegen ausserhalb des Repos auf dem Host, meistens unter `/mnt/user/appdata/secrets/`.
+
+## Zielbild des Homelabs
+
+- stabile Compose-first Infrastruktur
+- keine produktiven Dockerman-/Ad-hoc-Container als Dauerzustand
+- Traefik als einziger oeffentlicher Web-Eingang
+- GitOps ueber Gitea + Komodo
+- klare Trennung von Web-Netz, Backend-Netz und app-internen Netzen
+- saubere Backup-/Restore-Faehigkeit ueber Borg, Dumps und dokumentierte Pfade
+- keine stillen Host-Hotfixes ohne Repo-/Doku-Abgleich
+
+## Architekturblocke
+
+### Ingress / Netzwerk
+
+- `traefik` nimmt 80/443 entgegen.
+- Docker-Labels definieren Service-Routing.
+- `traefik/dynamic/*` bleibt nur fuer Middlewares, TLS und Dashboards.
+- Neue Service-Routen gehoeren nicht in den File-Provider.
+
+### DNS / Remote
+
+- AdGuard Home beantwortet LAN-DNS und nutzt Unbound als Upstream.
+- Tailscale stellt Remote-Zugang bereit und nutzt `network_mode: host`.
+
+### GitOps
+
+- Gitea hostet das Repo unter `git.kaleschke.info`.
+- Komodo ist Stack-Manager und Deploy-Consumer.
+- Komodo Periphery braucht Docker-Socket und `/mnt/user/services` Mount, um Stacks reproduzierbar zu deployen.
+
+### Identity / Security
+
+- Authelia stellt ForwardAuth fuer viele Admin-UIs bereit.
+- Vaultwarden ist ein separater Passwort-Tresor.
+- Komodo ist bewusst nicht pauschal hinter Authelia, weil UI, API, Webhooks und Periphery-WebSocket sonst leicht gebrochen werden koennen.
+
+### Apps
+
+Wichtige Apps sind Paperless, Immich, Mealie, Mail Archiver, Nextcloud, ntfy, Vaultwarden und Gitea. Admin-/Ops-Tools sind u. a. Homepage, Komodo, Borg UI, Backrest, Uptime Kuma, Filebrowser, code-server, Glances, Scrutiny, Speedtest, Grafana und Hermes Agent.
+
+### Monitoring / Metriken
+
+- Grafana laeuft unter `grafana.kaleschke.info` hinter Traefik + Authelia.
+- InfluxDB 3 Core ist nicht public und nicht im `frontend_net`.
+- Home Assistant schreibt ueber LAN-only Port 8181 nach InfluxDB, gebunden ueber `INFLUXDB_BIND_IP`.
+- Ein `401 Unauthorized` von InfluxDB ohne Token ist beim Reachability-Test ein Erfolgssignal.
+
+## Deployment-Logik
+
+Normalfall:
+
+1. lokaler Clone synchronisieren
+2. betroffene Dokumente und Compose-Datei lesen
+3. minimal aendern
+4. lokal validieren
+5. committen und pushen
+6. Komodo-Webhook / Deploy beobachten
+7. Runtime testen
+8. Doku aktualisieren
+
+Wichtig: Komodo-Web-Editor ist nicht der Bearbeitungsort. Wenn Komodo und Git voneinander abweichen, zuerst Git und Komodo Workspace pruefen, nicht live herumprobieren.
+
+## Netzwerkmodell
+
+| Netzwerk | Bedeutung |
+|---|---|
+| `frontend_net` | Web-/Proxy-Netz fuer Traefik-geroutete Dienste und Dienste mit Internetbedarf |
+| `backend_net` | internes Netz fuer shared PostgreSQL, Redis und Backends |
+| `dns_net` | AdGuard + Unbound |
+| app-interne Netze | Isolation von App + DB/Cache, z. B. Immich, Mealie, Nextcloud, Grafana/Influx |
+| `host` | nur dokumentierte Sonderfaelle wie Tailscale/Plex |
+
+Regeln:
+
+- Datenbanken nie ins `frontend_net`.
+- Admin-UIs nur mit Traefik + Middleware oder dokumentierter Ausnahme.
+- Direkte Host-Ports sind Ausnahme, nicht Default.
+- Runtime-Netznamen koennen Compose-Projektpraefixe bekommen, z. B. `grafana_grafana_influx_lan`.
+
+## Security-Modell
+
+- Secrets nie ins Git.
+- Werte niemals zitieren, auch nicht aus `.env`, Stack ENV, Logs oder Screenshots.
+- Secret-Dateien bevorzugt unter `/mnt/user/appdata/secrets/`.
+- `_FILE`-Varianten bevorzugen, falls Image sie unterstuetzt.
+- Wenn `_FILE` nicht unterstuetzt wird, Komodo Stack Environment Variables verwenden.
+- Docker-Socket, `privileged: true`, Host-Netz und breite Mounts sind nur mit dokumentierter Begruendung akzeptabel.
+
+Bekannte Ausnahmen:
+
+- Traefik: 80/443
+- Gitea: SSH 222
+- AdGuard: DNS 53 und Admin 8082
+- Tailscale: Host-Netz
+- Scrutiny: privileged
+- Komodo: Docker-Socket, native Auth
+- InfluxDB: LAN-only 8181 fuer Home Assistant Writer
+- Traefik dynamic config: manueller Host-Sync
+
+## Backup- und Restore-Modell
+
+Borg sichert kritische Appdaten, Secrets, Traefik-State und Dump-Artefakte. Datenbank-Restore soll bevorzugt ueber Dumps laufen, nicht ueber rohe Live-DB-Verzeichnisse.
+
+Wichtige Pfade:
+
+- `/mnt/user/appdata`
+- `/mnt/user/appdata/secrets`
+- `/mnt/user/services`
+- `/mnt/user/documents`
+- `/mnt/user/photos`
+- `/mnt/user/backups/borg/dumps/latest`
+
+Dump-Skript:
+
+- `ops/borg-ui/scripts/pre-backup-dumps.sh`
+- soll auf dem Unraid Host laufen
+- soll nicht als Borg-UI Inline-Hook behandelt werden, solange die Architektur nicht bewusst geaendert wird
+
+Disaster Recovery folgt einer Bootstrap-Reihenfolge:
+
+1. Traefik, AdGuard, Tailscale
+2. PostgreSQL, Redis, Authelia, Gitea
+3. Komodo
+4. kritische Apps
+5. restliche Apps/Ops
+
+## Typische Arbeitsweise im Repo
+
+- Fuer Fragen zuerst `HOMELAB_ARCHITECTURE_MASTER_V2.md` lesen.
+- Fuer operative Aenderungen `docs/WORKFLOW.md` lesen.
+- Fuer Service-Details `docs/SERVICE_CATALOG.md` und die Compose-Datei lesen.
+- Fuer Drift `docs/GITOPS_DRIFT_RUNBOOK.md` nutzen.
+- Fuer Rollback `docs/ROLLBACK.md` nutzen.
+- Fuer Restore `docs/DISASTER_RECOVERY.md` und `docs/RESTORE_MATRIX.md` nutzen.
+
+KI-Agenten sollen konservativ arbeiten: keine indirekten Live-Aenderungen, keine Deployments, keine Commits, keine Host-Schreibbefehle, wenn der Benutzer nur Analyse oder Doku verlangt.
+
+## Bekannte Risiken und Altlasten
+
+- Traefik dynamic config muss manuell auf den Host synchronisiert werden; Komodo deployed diese Dateien nicht automatisch.
+- `backend_net` und app-interne Netze muessen bei Runtime-Problemen live geprueft werden, weil Compose-Projektpraefixe Netznamen veraendern koennen.
+- Authelia Template und Compose-Middlewares koennen auseinanderlaufen; bei Auth-Aenderungen beide Seiten pruefen.
+- `paperless-ngx` nutzt fuer DB/Redis bewusst Stack ENV statt `_FILE`.
+- `homepage`, `glances` und `komodo-periphery` nutzen Docker-Socket-Mounts; Zugriff bewusst behandeln.
+- `backrest`, `borg-ui` und `filebrowser` haben breite Mounts; bei Hardening nicht ad hoc, sondern gezielt vorgehen.
+- `scrutiny` ist privilegiert und hat Device-Mounts.
+- `Plex-Media-Server` ist im Architekturziel als Host-Sonderfall dokumentiert, aber nicht als Repo-Compose-Stack enthalten.
+- `ops/hermes-agent/stack.env` liegt als echte Env-Datei im Repo. Werte wurden fuer dieses Kontextpaket nicht gelesen; pruefen, ob daraus ein Example/Host-Only-Modell werden soll.
+- Einige Images nutzen mutable Tag plus Digest. Das friert den aktuellen Digest ein, ist aber kein automatisches Upgrade-Modell.
+
+## Arbeitsregel bei Unsicherheit
+
+Nicht raten. Erst diese Reihenfolge:
+
+1. Repo-Doku lesen
+2. Compose-Datei lesen
+3. Git-Stand pruefen
+4. Komodo Workspace pruefen
+5. Docker Runtime pruefen
+6. Host-Listener / echten Request pruefen
+7. genau eine abweichende Ebene benennen
+
+Wenn zwei Reparaturversuche scheitern: keine weiteren Schreibbefehle, Pflichtmatrix aus `docs/GITOPS_DRIFT_RUNBOOK.md` ausfuellen.