209 lines
10 KiB
Markdown
209 lines
10 KiB
Markdown
# 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.
|
|
- 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. Homepage, Komodo, Borg UI, Uptime Kuma, Filebrowser, code-server, Glances, Scrutiny, Speedtest, 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.
|
|
- `ops/loki` und `ops/grafana-influxdb` sind abgeloeste Altstaende und sollen nach erfolgreichem Monitoring-Deploy nicht parallel betrieben werden.
|
|
|
|
## 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, `NET_ADMIN`, `NET_RAW`, `/dev/net/tun`
|
|
- Scrutiny: privileged
|
|
- Komodo: Docker-Socket, native Auth
|
|
- InfluxDB: LAN-only 8181 fuer Home Assistant Writer
|
|
- Grafana/InfluxDB: `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`.
|
|
- `homepage`, `glances` und `komodo-periphery` nutzen Docker-Socket-Mounts; 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.
|