Ops-dashboard/docs/specs/functional.md

Functionele specificatie — Ops Dashboard

Doel

Eén web-UI waarmee de eigenaar van een single-host server-stack (Docker + systemd + Git-checkouts + Caddy + Postgres) dezelfde operaties kan uitvoeren die anders in een SSH-terminal gebeuren — met audit-log, herhaalbare flows en minder typefouten.

Schaal: één host, één admin-gebruiker. Multi-host/team is buiten scope.

Gebruikers en rollen

Rol	Beschrijving	Hoeveelheid
admin	Volle toegang tot alle modules en flows. Single account, geseed via env.	1

Geen RBAC, geen tenant-isolatie, geen "view-only"-modus. Wie inlogt kan alles.

Functionele scope per module

Dashboard (/)

5 live status-widgets met auto-refresh ~5s:

Widget	Data-bron	Indicator
Docker	docker ps --format json	Count van running containers, lijst (naam + status)
Git	git status --short --branch per pad in REPO_PATHS	Branch + dirty-vlag
systemd	systemctl is-active <unit> per item in SYSTEMD_UNITS	Active / Inactive / Failed
Caddy	caddy admin-cmd certificates (of equiv. shell-output parse)	Aantal certs + dichtstbijzijnde expiry
Audit	DB-query op FlowRun desc	Laatste run + status

Acceptatie:

• Widget laadt < 1 s na page-load
• Auto-refresh werkt in achtergrond zonder volledig herrenderen
• Bij fout (agent down, command faalt): widget toont rood errorblok, niet de hele page

Auth (/login)

• Email + wachtwoord (single user)
• 5 failed attempts in 1 minuut → 429 rate-limit per IP
• Succesvolle login → session-cookie 24u, HttpOnly, SameSite=strict, Secure (production)
• /api/auth/logout invalideert sessie en wist cookie

Docker (/docker)

• Lijst running containers (CONTAINER ID, IMAGE, COMMAND, CREATED, STATUS, PORTS, NAMES)
• Auto-refresh elke 5s
• /docker/[name] → detail-page met logs (laatste 200 regels), image-info, environment
• Geen start/stop/restart vanuit UI — alleen via flows

Git (/git)

• Per pad in REPO_PATHS: huidige branch, ahead/behind count, modified-files-count, laatste 3 commits
• /git/[repo] → diff-viewer voor uncommitted changes + commit-historie laatste 20

systemd (/systemd)

• Per unit in SYSTEMD_UNITS: active/inactive/failed, last-changed-timestamp
• /systemd/[unit] → laatste 100 journal-regels van die unit, met level-filter
• Restart-actie: alleen voor units die expliciet in sudoers.d/ops-agent met NOPASSWD staan

Caddy (/caddy)

• Toon huidige /srv/scrum4me/caddy/Caddyfile met syntax-highlighting
• Toon alle uitgegeven certs (subject, issuer, expiry, dichtstbijzijnde eerst)
• Geel-warning bij expiry < 30 dagen, rood bij < 7 dagen
• /caddy/edit → editor met save-knop; save valideert via caddy validate voor commit en restart van caddy-container

Flows (/flows)

Twee voor-gedefinieerde flows in YAML in ops-agent/flows.example/:

Flow	Stappen
update_scrum4me_web	git pull → npm run build → docker compose up -d --build → smoke-test op homepage
update_caddy_config	write nieuw Caddyfile → caddy validate → docker compose restart caddy → check cert renewal

Per flow:

• Dry-run default (toont alleen wat het zou doen)
• "Run"-knop voert echt uit; toont live SSE-stream van stdout/stderr per stap
• Bij stap-fail: stop, markeer FlowRun als failed, latere stappen niet uitgevoerd
• Bij success: FlowRun = success, totaalduur opgeslagen

Audit (/audit)

• Lijst van alle FlowRun records, default 50 laatste, sort desc op started_at
• Filter op status, datumrange, flow-name
• /audit/[flow_run_id] → volledige output per stap, scrollable

Settings/Backups (/settings/backups)

• Lijst van .sql.gz bestanden in /srv/scrum4me/backups, met size + mtime
• "Backup now"-knop → maakt nieuwe dump met pg_dumpall voor alle databases
• Restore: handmatig vanuit terminal — UI toont alleen de stappen als runbook

State-machine flows

       ┌────────┐
       │ pending │
       └────┬────┘
            │ (start request)
       ┌────▼────┐
       │ running │
       └────┬────┘
       ┌────┼────┬────────┐
       ▼    ▼    ▼        ▼
   success failed cancelled timeout (>30min)

pending → running: bij ontvangst start-request running → success: alle stappen exit-code 0 running → failed: een stap exit-code ≠ 0 running → cancelled: user klikt cancel running → timeout: na 30 min nog steeds running (cleanup-job)

Hard limits

• Max 1 actieve flow tegelijk (lock-file in /var/run/agent/); 2e start-request → 409 Conflict
• Stdout/stderr per stap geknipt op 64 KB om audit-log niet te laten exploderen
• Session-TTL hard 24 uur, geen "remember me"
• Auto-refresh max 1 keer per 5 seconden om agent niet te overbelasten

Niet-functionele eisen

Eis	Doel
First load < 1s	Single-user, lokale Postgres, geen onnodige round-trips
Module-page TTI < 2s	Server-side render met direct agent-call, geen client-fetch waterval
Audit-trail volledig	Elke flow-start logt user + tijdstempel + args; elke command-execution logt exit + duration
Geen geheime data in URLs	Tokens in headers, secrets nooit in query-params
CSP strict	script-src 'self' 'unsafe-inline'; geen externe CDNs
HTTPS-only in productie	Caddy auto-ACME; cookies Secure-flag in prod-mode

Buiten scope

• Meerdere admins / RBAC
• Meerdere hosts / cluster-management
• Custom container starten (alleen restart bestaande)
• Real-time alerts (geen pager, geen email)
• Externe monitoring-integratie (Grafana/Prometheus/Sentry)
• Wachtwoord-reset-flow / SSO

Verwante documenten

• Technische specificatie — hoe het werkt
• Handleiding — hoe je het gebruikt
• Post-install runbook — eerste deploy