homelab-infra/docs/AI_CONTEXT.md

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.
• Neue produktive Komodo-Stacks aus Micha/homelab-infra muessen einen aktiven Gitea->Komodo-Webhook auf die aktuelle Stack-ID haben; Ausnahmen wie deaktivierte/pausierte Stacks muessen dokumentiert werden.
• Der komodo-Self-Stack ist eine dokumentierte Ausnahme ohne aktiven Gitea-Webhook; Bootstrap/Recovery laeuft ueber docs/SERVICES_RECOVERY.md.

Identity / Security

• Authelia stellt ForwardAuth fuer viele Admin-UIs bereit.
• Authelia nutzt GMX SMTP fuer Identity-/2FA-Benachrichtigungen; Passwort liegt als Host-Secret authelia_smtp_password.txt.
• 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.
• Komodo-Compose, Komodo-Secrets und Komodo-Runtime nur gemeinsam mit dem Betreiber aendern; KOMODO_WEBHOOK_SECRET ist bewusst getrennt von KOMODO_SECRET_KEY. Gitea-Webhooks nicht pauschal vereinheitlichen: einzelne Komodo-Stacks koennen eigene per-Stack-Webhook-Secrets haben.

Apps

Wichtige Apps sind Paperless, Immich, Mealie, Mail Archiver, Nextcloud, ntfy, Vaultwarden und Gitea. Admin-/Ops-Tools sind u. a. Glance, Komodo, Borg UI, Filebrowser, code-server, Glances, Scrutiny, Speedtest, Monitoring Grafana und Hermes Agent.

Hermes Agent — Architektur und Ops-Monitor

Hermes laeuft nach Model C (siehe ops/hermes-agent/README.md):

• hermes-gateway als Docker-Container auf dem Unraid-Host, intern auf hermes_net:8642
• Terminal-Befehle werden via SSH auf eine dedizierte Linux-VM ausgefuehrt
• VM-IP: 192.168.178.143, SSH-User: hermes
• Repo-Clone auf der VM: /srv/hermes-workspace/homelab-infra/

Fuer KI-Agenten wichtig: Das Hermes-Terminal laeuft auf der VM, nicht auf dem Unraid-Host. /mnt/user/...-Pfade sind von der VM aus nicht direkt erreichbar. Docker-CLI ist auf der VM nicht installiert — fuer Homelab-Checks wird check_health.py verwendet.

Ops-Monitor (homelab-ops-monitor):

• Skill: ops/hermes-agent/skills/homelab-ops-monitor.md
• Script: ops/hermes-agent/scripts/check_health.py — prueft Services via HTTP, keine externen Deps
• Wissensbasis: ops/hermes-agent/services.json — maschinenlesbare Ableitung aus docs/SERVICE_CATALOG.md
• Check-Strategie: HTTP GET fuer URL-basierte Services, interne Services (DBs, Redis) als "internal" markiert
• ntfy-Topic fuer Alerts: homelab-alerts auf https://ntfy.kaleschke.info

Nach Aenderungen an services.json oder check_health.py: git pull auf der VM ausfuehren.

• Mail Archiver ist ein Hybrid-Dienst mit frontend_net fuer IMAP/Traefik und backend_net fuer PostgreSQL; die Web-UI liegt hinter Authelia und behaelt zusaetzlich App-eigene Auth.

Monitoring / Metriken

• Zielzustand ist ein zentraler Stack monitoring/ unter https://monitoring.kaleschke.info.
• monitoring-grafana ist die zentrale UI fuer Prometheus, Loki und InfluxDB 3 Core.
• monitoring-prometheus sammelt Infrastruktur-Metriken; monitoring-loki + monitoring-promtail sammeln Docker-Logs.
• monitoring-influxdb3-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.
• Die frueheren Altstaende ops/loki und ops/grafana-influxdb wurden aus dem aktiven Repo entfernt; fuer Monitoring immer monitoring/ verwenden, Rollback nur ueber Git-Historie.
• Uptime Kuma ist entfernt; HTTP-Verfuegbarkeit laeuft ueber Blackbox Exporter, Prometheus-Alerts und Homelab / Availability in Monitoring Grafana.

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.

Beim Anlegen neuer produktiver Stacks ist der Gitea->Komodo-Webhook Pflicht. Nach dem Anlegen muss ein Test-Push oder Test-Delivery zeigen, dass Gitea die aktuelle Komodo-Stack-ID erreicht.

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, Monitoring
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. monitoring_monitoring_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 direkt; Admin 8082 ist bewusst ohne Traefik/2FA, aber auf Tailscale-IP 100.80.98.33 begrenzt
• Tailscale: Host-Netz, NET_ADMIN, NET_RAW, /dev/net/tun
• Scrutiny: privileged
• Komodo: Docker-Socket, native Auth
• InfluxDB: LAN-only 8181 fuer Home Assistant Writer
• monitoring-influxdb3-core: user: "0" als dokumentierte Host-Appdata-Permissions-Ausnahme
• 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, Authelia, Redis, Gitea
3. Komodo
4. kritische Apps
5. restliche Apps/Ops inklusive Hermes Agent

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 configuration.yml ist Repo-Baseline fuer nicht geheime Einstellungen, wird aber nicht automatisch von Komodo auf den Host kopiert; die produktive Host-Datei kann OIDC-/Secret-Konfiguration enthalten. Bei Auth-Aenderungen Repo-Baseline, Host-Config und Compose-Middlewares pruefen und nicht blind ueberschreiben.
• Authelia nutzt PostgreSQL, aber bewusst kein Redis-Session-Backend; Redis ist kein Authelia-Bootstrap-Blocker.
• Authelia-Notifier ist SMTP; bei Auth-Aenderungen Host-Config backupen, authelia validate-config ausfuehren und erst danach neu starten.
• paperless-ngx nutzt fuer DB/Redis bewusst Stack ENV statt _FILE.
• glance-docker-socket-proxy, glances und komodo-periphery nutzen Docker-/Socket-Zugriff; Zugriff bewusst behandeln.
• 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.
• Echte stack.env- und .env-Dateien gehoeren nicht ins Repo; fuer Hermes liegt nur ops/hermes-agent/stack.env.example im Git.
• Einige Images nutzen mutable Tag plus Digest. Das friert den aktuellen Digest ein, ist aber kein automatisches Upgrade-Modell.
• Stateful Images werden bevorzugt als Minor-/Patch-Tag plus Digest gepinnt; Redis-Caches bleiben bewusst ungedigestet.

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.