# Serverpuls – Server-Monitoring in WOMS

Stand: 2026-09-30 · Status: Design vom Nutzer im Chat freigegeben, Spec zur Prüfung

## Ziel

Ein neuer Navbar-Eintrag **Serverpuls** in WOMS (ticket.webklar.com) zeigt Admins die
Auslastung des Servers und das Wachstum der einzelnen Projekte über Tage, Wochen und
Monate – als Verlaufskurven „wie bei Aktien“. Feste Warnregeln (keine KI) melden
Probleme per E-Mail in drei Stufen.

Ausdrücklich **nicht KI-gesteuert**: Messung, Auswertung und Mails laufen
deterministisch in einem kleinen Dienst ohne Claude.

## Rahmenbedingungen

- Server: 8 Kerne, 15 GB RAM, 4 GB Swap (am 2026-09-30 voll), Platte 150 GB (76 % belegt),
  ~61 Container. Der Dienst selbst muss sehr sparsam sein (Limit 128 MB RAM, 0,5 CPU).
- WOMS ist eine statische React/Vite-SPA auf Appwrite; Server-Logik liegt in kleinen
  Node-Diensten hinter dem WOMS-nginx (Vorbild: `ticket-integrations`,
  `/api/integrations/`, Auth über Appwrite-JWT).
- Admin in WOMS = Appwrite-Konto mit Label `admin` (`AuthContext.jsx`).
- Der Deploy-Webhook von WOMS deployt jeden gepushten Branch; live geht nur per Push
  des Nutzers nach `test`.

## Entscheidungen

| Frage | Entscheidung |
|---|---|
| Name | Serverpuls |
| Rolle der KI | keine; feste Warnregeln |
| „Projekt“ | jede App / jeder Container (Previews als eigene Apps) mit CPU, RAM, Speicher |
| Warnkanal | E-Mail in drei Stufen Low / Medium / Critical |
| Mail-Takt | Critical sofort, Medium Sammelmail täglich 07:00, Low Wochenübersicht Mo 07:00 |
| Mail-Adresse | `server@webklar.com` ist Absender **und** einziger Empfänger |
| Umsetzung | eigener schlanker Dienst (kein Beszel, kein Netdata) |
| Sichtbarkeit | nur Admins (Navbar und API) |

## Architektur

```
Host /proc (ro) ──┐
docker-socket-proxy (nur GET containers/stats) ──┼──> serverpuls (Node 22, SQLite) ──> SMTP server@
/home/webklar/apps + Docker-Volumes (ro) ──┘            │
                                                        └── HTTP :8091  <── WOMS-nginx /api/serverpuls/  <── ServerpulsPage (uPlot)
```

### Einheiten

1. **Collector** (`collect/`): liest Messwerte, gibt reine Datenobjekte zurück.
   - `host.js` – `/proc/stat` (CPU % aus Differenz), `/proc/meminfo` (RAM verfügbar,
     Swap), `/proc/loadavg`, Zombies = Prozesse mit State `Z` in `/proc/*/stat`.
     Plattenbelegung `/` per `statfs` auf `/host/apps` (gleiches Dateisystem `/dev/sda1`).
   - `docker.js` – über den Socket-Proxy: Container-Liste (Name, Compose-Projekt/-Service,
     Status, Health, RestartCount) und `stats?stream=false` (CPU %, RAM).
   - `sizes.js` – Größe pro App: Ordner unter `/home/webklar/apps/<app>` plus Docker-
     Volumes der Container dieser App (`du -sb`, unter `nice -n 19 ionice -c3`).
     Außerdem „Aufräumbar“: ungenutzte Images, Build-Cache, gestoppte Container
     (`/system/df` über den Proxy).
2. **App-Zuordnung** (`apps.js`): Container → App über das Label
   `com.docker.compose.service` bzw. den Containernamen; eine kleine Mapping-Datei
   `config/apps.json` erlaubt Umbenennen/Zusammenfassen (z. B. `webklar-ticket-*` →
   „Ticketsystem“) und Ordnerzuordnung. Previews erscheinen einzeln.
3. **Speicher** (`store.js`): SQLite (`node:sqlite`) im Volume `serverpuls-data`.
   - Tabellen: `host_samples`, `app_samples`, `app_sizes`, `cleanup_samples`,
     `alerts` (Zustand), `mail_queue`.
   - Aufbewahrung: Rohwerte (5 min) 7 Tage → Stundenmittel/-max 90 Tage →
     Tageswerte unbegrenzt. Verdichtung täglich 03:30.
   - Erwartete Größe < 100 MB/Jahr.
4. **Regeln** (`rules.js`): reine Funktion `(aktuelle + historische Werte) → Liste aktiver
   Befunde {id, level, titel, wert, seit}`. Schwellen in `config/rules.json`.
5. **Alarmierung** (`alerts.js`): vergleicht Befunde mit gespeichertem Zustand, erzeugt
   Mails (sofort/täglich/wöchentlich), Wiederholungssperre 24 h, „✅ behoben“-Mail beim
   Verschwinden. Zustand in SQLite → Neustart erzeugt keine Doppel-Mails.
6. **Mailer** (`mail.js`): nodemailer, `mail.your-server.de:587` STARTTLS, Login
   `server@webklar.com`. Fehlgeschlagene Mails bleiben in `mail_queue` und werden
   alle 5 min erneut versucht (max. 24 h).
7. **API** (`api.js`): HTTP-Server Port 8091, Basis `/api/serverpuls`. Jede Anfrage
   (außer `/health`) braucht `X-Appwrite-JWT`; der Dienst fragt `/account` bei Appwrite
   ab (Cache 60 s) und verlangt Label `admin`, sonst 401/403.
8. **Scheduler** (`main.js`): 5-min-Takt, nächtliche Größenmessung 03:00, Verdichtung
   03:30, Medium-Digest täglich 07:00, Low-Wochenübersicht Mo 07:00 (Europe/Berlin).

### Messung

- Alle 5 Minuten: Server gesamt (CPU %, Load 1/5/15, RAM verfügbar, Swap belegt,
  Platte `/`, Zombies) und pro Container (CPU %, RAM, Status, Neustarts).
- Täglich 03:00: Größe pro App und „Aufräumbar“-Werte.
- Fällt eine Messung aus, wird **kein** Wert geschrieben (Lücke statt falscher Null).

## Warnregeln

Wichtige Container („kritisch“): Traefik, Appwrite, Kundenportal, Ticketsystem,
ticket-integrations, Gitea, InvoiceNinja, n8n (Liste in `config/rules.json`).

**🔴 Critical – sofortige Mail**
- Platte `/` ≥ 90 %
- RAM verfügbar < 500 MB **und** Swap ≥ 90 %, 10 min lang
- Load (5 min) > 24, 15 min lang
- kritischer Container läuft nicht oder > 3 Neustarts pro Stunde
- Zombies ≥ 100

**🟠 Medium – Sammelmail täglich 07:00**
- Platte `/` ≥ 80 %
- Swap ≥ 75 % oder RAM verfügbar < 1,5 GB, jeweils 1 h lang
- Zombies ≥ 20
- App wächst in 7 Tagen um > 20 % oder > 2 GB
- Load (5 min) > 8, 1 h lang
- nicht-kritischer Container abgestürzt (exited ≠ 0 oder Restart-Schleife)

**🟡 Low – Wochenübersicht Mo 07:00**
- ungenutzte Docker-Images > 10 GB oder Build-Cache > 3 GB
- App wächst in der Woche um > 10 %
- Zombies (≥ 1) halten sich > 24 h
- immer enthalten: Top 5 größte Apps, Top 5 schnellstes Wachstum, Top 5 RAM

**Allgemein**
- Dieselbe Warnung (gleiche `id`) höchstens 1× pro 24 h erneut gemeldet.
- Beim Verschwinden: Mail „✅ behoben“ (in derselben Taktung wie die Stufe; bei
  Critical sofort).
- Alle aktiven Warnungen stehen jederzeit auf der Seite.
- Wird eine Warnung höher eingestuft (Medium → Critical), gilt sofort die höhere Stufe.

## API

Alle Antworten JSON, Zeitstempel ISO/UTC.

| Methode + Pfad | Inhalt |
|---|---|
| `GET /health` | ohne Auth; `{ok, lastSample}` |
| `GET /overview` | aktuelle Serverwerte, 24-h-Minikurven, Trend ggü. gestern, aktive Warnungen, Zeitpunkt der letzten Messung |
| `GET /host?metric=cpu\|ram\|swap\|load\|disk\|zombies&range=24h\|7d\|30d\|90d\|1y` | Zeitreihe; Auflösung abhängig vom Zeitraum |
| `GET /apps` | Tabelle: Name, CPU %, RAM, Speicher, Δ 7 T, Δ 30 T, Speicher-Minikurve (30 T) |
| `GET /apps/:id?range=…` | Zeitreihen Speicher, RAM, CPU für eine App |
| `GET /cleanup` | ungenutzte Images, Build-Cache, gestoppte Container mit Größe |

Nur lesend. Es gibt **keine** Endpunkte zum Löschen, Stoppen oder Ändern.

## WOMS-Seite „Serverpuls“

- Navbar-Eintrag mit Pulssymbol, nur für `isAdmin`; roter/oranger Punkt bei aktiver
  Critical/Medium-Warnung (aus `/overview`, beim Laden der App und alle 5 min).
- Route `/serverpuls`; Nicht-Admins werden umgeleitet.
- Aufbau:
  1. **Kopf mit Ampel**: 🟢 Alles ok / 🟠 n Warnungen / 🔴 Critical, darunter die
     aktiven Warnungen (Stufe, seit wann, Wert). Hinweis „letzte Messung vor X Min.“;
     gelb, wenn älter als 15 min.
  2. **Kacheln**: CPU, Load, RAM, Swap, Platte, Zombies – aktueller Wert, 24-h-Minikurve,
     Trend ggü. gestern.
  3. **Großes Diagramm** (uPlot): Zeitraum 24 h / 7 T / 30 T / 90 T / 1 J, Wert
     wählbar, Tooltip mit exaktem Wert.
  4. **Tabelle „Projekte“**: sortierbar, Suchfeld, Δ-Spalten grün/rot mit Pfeil,
     Minikurve; Klick öffnet Detaildiagramm der App.
  5. **„Aufräumbar“**: reine Anzeige.
- Aktualisiert sich jede Minute, solange sichtbar. Handy: Kacheln untereinander.
- Neue Abhängigkeit: `uplot`. Lockfile wie bisher in einem Wegwerf-`node:20-alpine`
  erzeugen (Deploy-Image).

## Betrieb / Deploy

- Code: `/home/webklar/apps/serverpuls/` (eigenes Git-Repo, nur lokal).
- `docker-compose.yml` (Backup vorher): Dienste `serverpuls` (`node:22-alpine`,
  `mem_limit: 128m`, `cpus: 0.5`, `init: true`; Host-`/proc` wird als `/host/proc:ro` gemountet,
  kein `pid: host`) und `serverpuls-docker-proxy`
  (`tecnativa/docker-socket-proxy`, nur lesend: `CONTAINERS=1`, `IMAGES=1`, `SYSTEM=1`
  für `/system/df`, `POST=0`), beide im `webklar-network`, ohne Traefik-Route.
- Mounts serverpuls: `/proc:/host/proc:ro`, `/home/webklar/apps:/host/apps:ro`,
  `/var/lib/docker/volumes:/host/volumes:ro`, `serverpuls-data:/data`.
- `.env`: `SERVERPULS_SMTP_USER=server@webklar.com`, `SERVERPULS_SMTP_PASS` – vom
  Nutzer über eine Erweiterung von `scripts/mail-zugang.py` gesetzt (Claude sieht das
  Passwort nicht).
- WOMS-nginx: `location /api/serverpuls/` → `http://serverpuls:8091` (wie
  `/api/integrations/`).
- WOMS-Code auf `feature/serverpuls` (Worktree `dev-serverpuls`, Basis `origin/test`).
  Live erst nach Push des Nutzers.

## Fehlerbehandlung

- Collector-Teilfehler (z. B. Proxy nicht erreichbar) → betroffene Werte fehlen, Rest
  wird gespeichert; Fehler im Log.
- Größenmessung hat Zeitlimit (30 min); bricht sie ab, bleiben die Vortageswerte stehen
  und die Seite zeigt deren Datum.
- SMTP-Fehler → `mail_queue`, erneuter Versuch alle 5 min bis 24 h.
- Appwrite nicht erreichbar → API 502, Seite zeigt Fehlerhinweis.

## Tests

- Unit: Regeln (Schwellen, Dauerbedingungen, Hoch-/Herabstufung, Wiederholungssperre,
  behoben), Verdichtung, Wachstumsberechnung, `/proc`-Parser mit Beispieldateien.
- API: gemocktes Appwrite (Admin → 200, ohne Label → 403, ohne JWT → 401).
- UI: bewährtes esbuild-/Playwright-Harness unter RAM-Limit mit API-Fixtures.
- Live-Check: Container-RAM < 128 MB, erste Messwerte, Test-Mail an server@.

## Nicht enthalten

- Keine Aktionen (Löschen, Neustarten) aus der Seite heraus.
- Keine KI-Auswertung.
- Keine automatischen Tickets (Warnungen nur per Mail und auf der Seite).