hermes infos

2026-05-06 20:26:29 +02:00
parent aded9a9cbc
commit 7161da00b3
3 changed files with 99 additions and 1 deletions
@@ -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: <https://github.com/NousResearch/hermes-agent>