From 7161da00b37257aa5c7e5d95c4159b1b1c5a6f7c Mon Sep 17 00:00:00 2001 From: Micha Date: Wed, 6 May 2026 20:26:29 +0200 Subject: [PATCH] hermes infos hermes infos --- docs/AI_CONTEXT.md | 23 ++++++++++++ docs/SERVICE_CATALOG.md | 2 +- ops/hermes-agent/README.md | 75 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 99 insertions(+), 1 deletion(-) diff --git a/docs/AI_CONTEXT.md b/docs/AI_CONTEXT.md index af08af4..92751ca 100644 --- a/docs/AI_CONTEXT.md +++ b/docs/AI_CONTEXT.md @@ -51,6 +51,29 @@ Traefik ist der zentrale Web-Einstieg fuer HTTP(S). Admin-/Ops-UIs liegen entwed ### 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. + +### 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 diff --git a/docs/SERVICE_CATALOG.md b/docs/SERVICE_CATALOG.md index b45497f..fa6b5c2 100644 --- a/docs/SERVICE_CATALOG.md +++ b/docs/SERVICE_CATALOG.md @@ -68,7 +68,7 @@ Secret-Werte sind nicht enthalten. Es werden nur Secret-Namen, Env-Key-Namen und | `code-server` | Web-Editor / Operations Workspace | `ops/code-server/docker-compose.yml` | `https://code.kaleschke.info` | Traefik + Authelia | `/mnt/user/appdata/code-server`, `/mnt/user/services/dev` | Tier 3 | ja + Authelia | `PASSWORD_FILE`; Workspaces beachten | | `grafana` | Metrik-Dashboard | `ops/grafana-influxdb/docker-compose.yml` | `https://grafana.kaleschke.info` | Traefik + Authelia, InfluxDB 3 Core | `/mnt/user/appdata/grafana`, Grafana provisioning | Tier 3 | ja + Authelia | Datasource wird provisioniert, Token ueber Secret; laeuft aktuell als `user: "0"` wegen Host-Appdata-Permissions | | `influxdb3-core` | Zeitreihen-/Metrikdaten fuer Grafana und Home Assistant | `ops/grafana-influxdb/docker-compose.yml` | LAN `8181` je `INFLUXDB_BIND_IP`, keine Public URL | Grafana, Home Assistant Writer | `/mnt/user/appdata/influxdb3/data`, `/mnt/user/appdata/influxdb3/plugins` | Tier 3 | nein | LAN-only Host-Port-Ausnahme; `401 Unauthorized` beim Curl ohne Token ist erwarteter Reachability-Test; laeuft aktuell als `user: "0"` wegen Host-Appdata-Permissions | -| `hermes-gateway` | Hermes Agent Gateway/API intern | `ops/hermes-agent/docker-compose.yml` | intern `8642` auf `hermes_net` | SSH Runner, LLM Provider, optional Home Assistant | `/mnt/user/appdata/hermes-agent/data`, SSH key path | Tier 3, Borg/Share | nein | kein Docker socket; terminal backend `ssh`; echte `.env` auf Host-Appdata | +| `hermes-gateway` | Hermes Agent Gateway/API intern | `ops/hermes-agent/docker-compose.yml` | intern `8642` auf `hermes_net` | SSH Runner (VM 192.168.178.143), LLM Provider, optional Home Assistant | `/mnt/user/appdata/hermes-agent/data`, SSH key path | Tier 3, Borg/Share | nein | kein Docker-Socket; terminal backend `ssh` auf dedizierte VM (192.168.178.143, User `hermes`, Repo unter `/srv/hermes-workspace/homelab-infra/`); Ops-Monitor-Skill `homelab-ops-monitor` aktiv; echte `.env` auf Host-Appdata | | `hermes-dashboard` | Hermes Dashboard | `ops/hermes-agent/docker-compose.yml` | `https://hermes.kaleschke.info` via `${HERMES_DASHBOARD_HOST}` | `hermes-gateway`, Traefik + Authelia | shared read-only data mount | Tier 3, Borg/Share | ja + Authelia | Compose-Profil `dashboard`; bindet intern mit `--insecure` auf `0.0.0.0`, externe Absicherung bleibt Authelia | ## Backup- und Restore-Hinweise diff --git a/ops/hermes-agent/README.md b/ops/hermes-agent/README.md index f23dfac..91a1998 100644 --- a/ops/hermes-agent/README.md +++ b/ops/hermes-agent/README.md @@ -425,6 +425,81 @@ Back up at least: - `/mnt/user/appdata/hermes-agent/ssh/known_hosts` - `/mnt/user/appdata/secrets/hermes_runner_id_ed25519` +## Phase 7 - Ops Monitor (homelab-ops-monitor) + +### Was es ist + +Ein Skill + Script das Hermes zum kontextuellen Ops-Assistenten macht. +Wenn ein Service ausfaellt, bekommt er nicht eine rohe Fehlermeldung, sondern einen +angereicherten Alert: Abhaengigkeiten, letzter Backup-Dump, erster Diagnoseschritt. + +### Laufzeit-Architektur (Stand 2026-05-06) + +- Hermes laeuft als Docker-Container auf dem Unraid-Host (hermes-gateway, hermes_net) +- Terminal-Backend SSH-Ziel: `192.168.178.143` (dedizierte Linux-VM, Model C) +- Hermes-User auf der VM: `hermes` +- Repo-Clone auf der VM: `/srv/hermes-workspace/homelab-infra/` +- Workspace-Verzeichnis auf der VM: `/srv/hermes-workspace/` + +Wichtig fuer KI-Agenten und Betreiber: Das 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 vorhanden und wird nicht benoetigt. + +### Dateien + +| Datei | Pfad im Repo | Pfad auf VM | +|---|---|---| +| Wissensbasis | `ops/hermes-agent/services.json` | `/srv/hermes-workspace/homelab-infra/ops/hermes-agent/services.json` | +| Health-Script | `ops/hermes-agent/scripts/check_health.py` | `/srv/hermes-workspace/homelab-infra/ops/hermes-agent/scripts/check_health.py` | +| Skill-Prompt | `ops/hermes-agent/skills/homelab-ops-monitor.md` | `/srv/hermes-workspace/homelab-infra/ops/hermes-agent/skills/homelab-ops-monitor.md` | + +### check_health.py + +- Keine externen Abhaengigkeiten — nur Python-Standardbibliothek (`json`, `urllib`, `ssl`) +- Kein Docker CLI, kein pip, kein Root noetig +- Prueft Services mit URL via HTTP GET (2xx/3xx/4xx = healthy, 5xx/Timeout = unhealthy) +- Interne Services ohne URL (Datenbanken, Redis) werden als `"internal"` markiert — kein Fehler +- Dump-Timestamps werden gelesen falls `/mnt/user/backups/borg/dumps/latest` erreichbar ist (optional) +- services.json wird relativ zum Script-Verzeichnis gesucht (`../services.json`) + +Verwendung auf der VM: +```bash +cd /srv/hermes-workspace/homelab-infra +python3 ops/hermes-agent/scripts/check_health.py --summary # Tier 1+2 +python3 ops/hermes-agent/scripts/check_health.py paperless-ngx # gezielt +python3 ops/hermes-agent/scripts/check_health.py --all # alle Tiers +``` + +### services.json + +Maschinenlesbare Wissensbasis abgeleitet aus `docs/SERVICE_CATALOG.md`. +Enthaelt fuer jeden Service: Tier, Container-Name, Abhaengigkeiten, Dump-Dateiname, +Datenpfade, first_check-Hinweis und betriebliche Notizen. + +Bei Aenderungen am Service Catalog: `services.json` und `services.yaml` parallel aktualisieren. + +### Skill importieren + +``` +„Bitte erstelle einen neuen Skill namens homelab-ops-monitor. Lies dazu die Datei +/srv/hermes-workspace/homelab-infra/ops/hermes-agent/skills/homelab-ops-monitor.md +und lege den Skill mit diesem Inhalt an." +``` + +Nach Repo-Aenderungen auf der VM pullen: +```bash +cd /srv/hermes-workspace/homelab-infra && git pull +``` + +### Bekannte Einschraenkungen + +- Interne Services (PostgreSQL, Redis, MongoDB) koennen nicht extern geprueft werden +- Dump-Timestamps nur lesbar wenn `/mnt/user/backups/` per NFS oder Mount erreichbar ist +- Docker-Healthstatus der Container ist von der VM aus nicht pruefbar (kein Docker-Socket) +- Alerting via ntfy erfordert dass ntfy selbst healthy ist (Fallback: Telegram) + +--- + ## Official sources used - Repository README: