monitor/README.md

🖥️ monitor

monitor überwacht mehrere Systeme (per Ping und/oder per REST-API-Meldungen entfernter Agenten) und zeigt den Zustand als interaktive Büro-Visualisierung (Kanban-Board + Monitor-Wand mit Agenten an Schreibtischen).

Der vollständige Umbauplan steht in Visualization.md (Roadmap Phase 0-7), die dazugehörigen Klärungen in Detailfragen.md und Detailantworten.md.

---

🚀 Features

• REST-API (api/, siehe API.md) für Tickets, Events, Systeme, KPIs und Agenten-Aktivität, mit statischen API-Keys pro Agent
• Büro-Visualisierung (html/office.html) als Vanilla-SVG-Szene: Kanban-Board, Monitor-Wand (Events/Systeme/KPIs), 8 Schreibtische - zeigt live die Daten aus der REST-API (Push per Server-Sent Events, Polling-Fallback), Klick auf Board/Monitore öffnet Detail-Modals, Agenten laufen animiert zwischen Schreibtisch/Board/Monitor-Wand/Kaffee-Ecke (Phase 3-5, siehe Visualization.md Abschnitt 9). Ist die API nicht erreichbar, zeigt die Szene ersatzweise Demo-Daten — kenntlich gemacht durch einen roten Banner „API nicht erreichbar!". Die Basis-URL der API kommt aus MONITOR_API_BASE (siehe .env.example).
• Klick auf den PO öffnet ein Modal, in dem sich die vom Codeberg-Sync gelesenen Projekte (Owner/Repo + Farbe) hinzufügen, bearbeiten und löschen lassen (Issue #27) — Änderungen wirken sofort im laufenden sync-Dienst, ohne Neustart. Schreibende Aktionen fragen einmalig den MONITOR_ADMIN_API_KEY ab und merken ihn sich im Browser.
• Klick auf das Zahnrad neben der Überschrift „Systeme" öffnet die Verwaltung der per Ping überwachten Hosts (Issue #70): Server hinzufügen, umbenennen und entfernen, ohne sich auf den Rechner mit check_fds.sh einzuloggen — der holt seine hosts.conf bei jedem Lauf von der API. Ein entfernter Host nimmt seine Kachel im System-Monitor mit; Kacheln ohne zugehörigen Host lassen sich im selben Dialog einzeln aufräumen.
• Codeberg-Sync als Dauerläufer (Compose-Service sync): füllt Backlog und Done automatisch aus den Issues mehrerer konfigurierter Codeberg-Projekte (je Projekt mit eigener Ticket-Farbe, siehe oben) — periodisch alle MONITOR_SYNC_INTERVAL Sekunden und, wenn ein Webhook eingerichtet ist, innerhalb von Sekunden nach jeder Issue-Änderung (POST /api/v1/webhooks/codeberg, HMAC-signiert per CODEBERG_WEBHOOK_SECRET). Siehe API.md Abschnitt „Codeberg-Sync" — dort steht auch die Einrichtung im Codeberg-Repo.
• Auto-Update auf einem Produktionsserver: Sobald ein PR nach main gemergt wird, kann deploy-webhook.py denselben update.sh anstoßen, den auch ein manuelles Update aufruft (Push-Webhook, HMAC-signiert per MONITOR_DEPLOY_WEBHOOK_SECRET) — siehe README_UPDATE.md.
• Weiterhin: klassische Ping-Überwachung (check_fds.sh, hosts.conf, mail_fds.py) als eine Datenquelle für den System-Monitor; die alte tabellarische Statusseite ist mit Phase 7 entfallen (F16), status.txt speist weiterhin den System-Monitor

---

📁 Projektstruktur

• api/ — REST-API (PHP, SQLite), siehe api/README.md
• html/ — Frontend: office.html (Büro-Visualisierung), js/, css/
• tests/frontend/ — Node-Tests für die Frontend-Layoutlogik (node --test)
• check_fds.sh, mail_fds.py, hosts-sample.conf, monitor-api-sample.conf — bestehende Ping-Überwachung (letztere: optionale Zugangsdaten für die Meldung per REST)
• docker-compose.yml — komplette Entwicklungsumgebung (siehe unten)
• update.sh — holt die neueste Version vom konfigurierten Git-Remote und aktualisiert die Docker-Compose-Umgebung (Abhängigkeiten, Images, Dienste, Tests)
• deploy-webhook.py, deploy/ — löst update.sh auf einem Produktionsserver automatisch aus, sobald ein PR nach main gemergt wird (Push-Webhook); siehe README_UPDATE.md
• register-agent.sh — Hilfsskript, um einen neuen Agenten per POST /api/v1/agents zu registrieren (siehe API.md Abschnitt "Agenten")
• register-ops-agent.sh — registriert den lokalen OPs-Agenten (Rolle ops) und legt dabei monitor-api.conf für die Statusmeldung des Ping-Checks an (siehe "Weg 3" unten)

---

🐳 Entwicklung (nur Docker, kein lokales PHP/Node nötig)

Analog zum NC-Gantt-Projekt läuft die gesamte Ausführung (Bauen, Entwickeln, Testen) in Docker-Compose-Containern; auf dem Host muss nichts installiert werden.

cp .env.example .env               # einmalig, MONITOR_ADMIN_API_KEY anpassen

docker compose up --build          # API auf :8091, Buero-Visualisierung auf :8090, Sync
docker compose run --rm api composer test      # PHPUnit (API)
docker compose run --rm frontend               # Node-Tests (Frontend-Layoutlogik)
docker compose logs -f sync                    # Codeberg-Sync mitlesen

Der Browser erreicht die API nicht über das Compose-Netzwerk, sondern über die in MONITOR_API_BASE (.env) hinterlegte URL — der Default http://localhost:8091/api/v1 passt zum Port-Mapping oben. Wer die Ports in docker-compose.yml ändert oder das System hinter einem Reverse Proxy betreibt, muss MONITOR_API_BASE entsprechend nachziehen, sonst zeigt die Szene den Banner „API nicht erreichbar!" und fällt auf Demo-Daten zurück. Der Webserver liefert den Wert zur Laufzeit als /config.js aus (docker/nginx/default.conf.template), ein Build-Schritt ist dafür nicht nötig.

Details zur API: api/README.md. Details zu den Endpunkten: API.md.

---

🖥️ Einen Server zur Überwachung hinzufügen

Der System-Monitor in der Büro-Visualisierung zeigt zunächst keine Kacheln an, solange kein System gemeldet wurde — dafür gibt es zwei unabhängige Wege:

Weg 1: Klassische Ping-Überwachung (hosts.conf)

1. hosts-sample.conf nach hosts.conf kopieren und um den neuen Server erweitern (eine Zeile pro Server, Format Hostname IP) — ist Weg 3 eingerichtet, geht das stattdessen über die Oberfläche (siehe „Hosts über die Oberfläche pflegen" weiter unten):

   Webserver 192.168.178.10
   

2. Optional, für E-Mail-Alarme bei Ausfall: credentials-sample.conf nach credentials.conf kopieren und die SMTP-Zugangsdaten eintragen (wird von mail_fds.py benutzt).
3. check_fds.sh regelmäßig ausführen, z.B. per Cron alle paar Minuten. Das Skript pingt jeden Eintrag aus hosts.conf dreimal an und schreibt das Ergebnis in status.txt (Pfad über STATUS_FILE im Skript einstellbar).
4. Die API liest status.txt laufend mit und zeigt die Einträge als Systeme (source: "legacy") im System-Monitor an — ohne dass etwas neu gestartet werden muss.

⚠️ Dieser Import liest MONITOR_STATUS_FILE als lokale Datei. Läuft check_fds.sh auf einem anderen Rechner als die API (oder liegt status.txt außerhalb des API-Containers — der Mount in docker-compose.yml ist standardmäßig auskommentiert), erreicht sie die API nie und der System-Monitor bleibt bei „Keine Systeme gemeldet". Fehlt die Datei, meldet die API keinen Fehler, sondern liefert eine leere Liste. In dem Fall Weg 3 verwenden.

Weg 2: Status direkt per REST-API melden

Eigene Server/Skripte können ihren Status auch ohne hosts.conf melden:

1. Einen Agenten registrieren (liefert einmalig einen API-Key zurück, siehe register-agent.sh bzw. API.md).
2. Mit diesem Key den Status senden:

   curl -X POST "$MONITOR_API_BASE/systems/mein-server/status" \
     -H "X-Api-Key: <API-Key>" \
     -H "Content-Type: application/json" \
     -d '{"status": "ok", "name": "Mein Server", "type": "host"}'
   

So gemeldete Systeme (source: "api") haben Vorrang vor dem Legacy-Import aus status.txt und werden von ihm nicht überschrieben. Details zu Feldern/Auth: API.md.

Weg 3: Ping-Überwachung, die ihre Ergebnisse selbst per REST meldet

Kombiniert beide Wege und ist der richtige Weg, wenn der Ping-Check auf einem anderen Rechner läuft als die API — dann fällt der Umweg über die Datei status.txt weg:

1. Wie in Weg 1 die hosts.conf pflegen und check_fds.sh per Cron laufen lassen.

2. Den OPs-Agenten registrieren — das erledigt register-ops-agent.sh neben der docker-compose.yml in einem Schritt (die API muss dafür laufen):

   ./register-ops-agent.sh            # optional: ./register-ops-agent.sh "OPs Rechenzentrum"
   

   Das Skript liest MONITOR_ADMIN_API_KEY und MONITOR_API_BASE aus der .env, legt einen Agenten der Rolle ops an (sitzt als „OPs" sichtbar an einem Schreibtisch, Issue #66) und schreibt den nur einmalig ausgegebenen API-Key mit chmod 600 nach monitor-api.conf. Eine bestehende monitor-api.conf überschreibt es nicht (--force erzwingt es).

   Von Hand geht es weiterhin so: Agenten wie in Weg 2 registrieren (Rolle ops), monitor-api-sample.conf nach monitor-api.conf neben check_fds.sh kopieren, dort MONITOR_API_BASE (ohne /api/v1) und MONITOR_API_KEY eintragen, chmod 600 setzen.

check_fds.sh meldet dann nach jedem Ping zusätzlich per REST (online → ok, offline → error) und schreibt status.txt unverändert weiter für den alten Wandmonitor. Die System-ID entsteht dabei aus dem Hostnamen (Nextcloud(intern) → nextcloud-intern), der Originalname bleibt als Anzeigename erhalten. Ist die API nicht erreichbar, läuft die Ping-Überwachung normal weiter und protokolliert nur eine Warnung.

⚙️ Hosts über die Oberfläche pflegen

Ist Weg 3 eingerichtet, muss für einen neuen oder entfernten Server niemand mehr die hosts.conf auf dem Ping-Rechner editieren (Issue #70): Ein Klick auf das Zahnrad neben der Überschrift „Systeme" öffnet die Verwaltung der überwachten Hosts — dasselbe Muster wie das Zahnrad am PO-Platz für die Codeberg-Projekte. Änderungen verlangen den MONITOR_ADMIN_API_KEY; der Browser fragt einmalig danach und merkt ihn sich lokal.

Wie die Liste auf den Ping-Rechner kommt:

• check_fds.sh holt sie bei jedem Lauf mit seinem Agenten-Key ab und schreibt daraus seine lokale hosts.conf. Von Hand editiert man die Datei danach nicht mehr — der nächste Cron-Lauf überschreibt sie.
• Beim ersten Lauf lädt der Check seine bestehende hosts.conf einmalig hoch, damit die schon überwachten Server nicht von Hand nachgetragen werden müssen. Danach hat die Oberfläche das letzte Wort: Ein dort entfernter Host kommt über diesen Weg nicht zurück.
• Ist die API nicht erreichbar, pingt der Check unverändert nach der zuletzt geschriebenen Datei weiter und protokolliert nur eine Warnung.

Ein hier entfernter Host nimmt seine Kachel im System-Monitor mit — auch die aus dem status.txt-Import, die unter dem unveränderten Hostnamen läuft. Kacheln, die zu keinem gepflegten Host gehören (etwa Server, die sich nach Weg 2 selbst melden, oder Reste eines längst entfernten Hosts), stehen im selben Dialog unter „Weitere Kacheln im System-Monitor" und lassen sich dort einzeln entfernen.

Voraussetzung ist ein registrierter OPs-Agent (register-ops-agent.sh, siehe Weg 3) — nur für Hosts, die von einem solchen Ping-Check geprüft werden, kann die Oberfläche die hosts.conf überhaupt pflegen. Server, die ihren Status nach Weg 2 selbst melden, bleiben unberührt.