# Handleiding — Ops Dashboard

Voor de dagelijkse beheerder van een single-host server-stack (Docker, systemd, Git, Caddy, Postgres). Deze handleiding beschrijft *hoe* je de app gebruikt, niet *hoe* hij werkt — voor dat laatste zie [`specs/technical.md`](./specs/technical.md).

## Eerste inlog

1. Open `https://<jouw-host>/` (bv. `https://ops.jp-visser.nl`).
2. Je wordt doorgestuurd naar `/login`. Vul de admin-credentials in die je tijdens deploy in `SEED_USER_EMAIL` / `SEED_USER_PASSWORD` hebt gezet.
3. Na succesvolle login zit je 24 uur ingelogd via een HttpOnly-cookie. Daarna opnieuw inloggen.

Wachtwoord vergeten? Geen reset-flow in de app — los op met een SQL-update:

```bash
# Genereer een nieuwe bcrypt-hash voor je nieuwe wachtwoord
docker run --rm -e PW='<nieuw-wachtwoord>' node:22-alpine sh -c '
  cd /tmp && npm init -y >/dev/null 2>&1 && npm install --silent bcryptjs >/dev/null 2>&1
  node -e "console.log(require(\"bcryptjs\").hashSync(process.env.PW, 12))"
'
# Plak in psql:
docker exec -it scrum4me-postgres psql -U scrum4me -d ops_dashboard \
  -c "UPDATE \"User\" SET pwd_hash = '<hash>' WHERE email = '<jouw-email>';"
```

## Dashboard (home)

Vijf live status-widgets, auto-refresh ~5 sec:

| Widget | Toont |
|---|---|
| **Docker** | Aantal draaiende containers + lijst |
| **Git** | Branch en uncommitted-status per geconfigureerd repo-pad |
| **systemd** | Service-status (active/inactive/failed) per geconfigureerde unit |
| **Caddy** | TLS-certs met dichtstbijzijnde expiratiedatum (geel = <30 dagen) |
| **Audit** | Laatste flow-run met timestamp en exit-status |

Klik een widget aan om naar de detail-pagina te gaan.

## Modules

### `/docker` — Containers

Tabel van `docker ps` met auto-refresh. Klik op een container-naam voor detail (logs, image, ports, status).

Read-only — geen start/stop/restart vanuit de UI. Voor wijzigingen: een **Flow** (zie hieronder).

### `/git` — Repositories

Per geconfigureerd pad in `REPO_PATHS` (env var): branch, uncommitted-files (M/A/D/??), laatste 3 commits. Klik door voor diff-viewer.

Read-only — pulls/commits gaan via een Flow.

### `/systemd` — Services

Lijst van services uit `SYSTEMD_UNITS` (env var). Toont status, laatste log-regels. Klik door voor full journal-tail van die unit.

Restart-knop: alleen voor units die in `commands.yml` zijn whitelisted én in `sudoers.d/ops-agent` met `NOPASSWD` staan.

### `/caddy` — Reverse-proxy & TLS

Toont de actieve Caddyfile (syntax-highlighted) plus alle TLS-certs (subject + expiry). "Edit"-knop opent een editor — opslaan **valideert** de Caddyfile via `caddy validate` voordat het wordt geschreven.

### `/flows` — Multi-step deployments

Twee voor-gedefinieerde flows:

- **Update Scrum4Me website** — pull main, build container, restart, smoke-test
- **Update Caddy config** — schrijf nieuwe Caddyfile, valideer, restart Caddy, verifieer dat alle hostnames nog reageren

Een flow draait stap-voor-stap met **dry-run** als standaard. Na dry-run zie je per stap wat het gaat doen. Klik "Run" om echt uit te voeren. Tijdens executie zie je live stdout/stderr per stap.

### `/audit` — Flow-runs

Chronologische lijst van alle gestarte flows: starttijd, duur, exit-status, wie 'm startte. Klik door voor de volledige output (stdout/stderr per stap).

### `/settings/backups` — Backups

Postgres backup-management:

- Lijst van bestaande dump-bestanden in `/srv/scrum4me/backups`
- "Backup now"-knop maakt een dump met timestamp-naam
- Restore-runbook (handmatige stappen — geen automatische restore vanuit UI om de blast-radius klein te houden)

## Veelvoorkomende taken

### Container hangt — wat nu?

1. `/docker` → klik container-naam → bekijk logs
2. Diagnose? Open een SSH-sessie en gebruik `docker logs`, `docker exec` etc. (Niet vanuit de UI — dat is buiten scope.)
3. Restart nodig? Voeg de container toe aan `commands.yml` whitelist (op de host) + run via `/flows`

### Caddy-config wijzigen

1. `/caddy` → "Edit"
2. Pas Caddyfile aan in de editor
3. Save → app draait `caddy validate` → bij succes wordt het geschreven en Caddy herstart
4. Verifieer in `/caddy` dat het cert-overzicht klopt

> Voor breaking changes (verkeerde syntax of niet-bestaande site): de validate-stap blokkeert. Bij twijfel: maak eerst een backup van `/srv/scrum4me/caddy/Caddyfile`.

### Sprint mergen via flow

`/flows/update-scrum4me-web` — kies branch (default `main`), klik dry-run, lees wat het doet, klik "Run". Stap-output stream live. Na success: smoke-test verifieert dat de homepage 200 geeft.

## Wat kan **niet** vanuit de UI

- SSH-toegang of arbitrary shell-commando's (alleen whitelisted commands.yml-keys)
- User-management (één admin via seed; multi-user is buiten scope)
- Container starten met andere image of args (alleen restart van bestaande)
- Wachtwoord reset (SQL-update vereist)
- Cert handmatig forceren (Caddy doet auto-ACME)

## Logs voor incident-response

| Component | Log-locatie |
|---|---|
| Dashboard app | `docker logs scrum4me-ops-dashboard` |
| ops-agent | `journalctl -u ops-agent -f` |
| Caddy | `docker logs scrum4me-caddy` |
| Postgres | `docker logs scrum4me-postgres` |

Audit-trail van wat-doet-wie-wanneer: tabel `FlowRun` + `FlowStep` in de `ops_dashboard` database, of via `/audit` in de UI.

## Veiligheidsadvies

- Houd port 3099 (ops-agent) **niet** open naar de buitenwereld. UFW-regel scoped op `172.18.0.0/16`. Zie [`runbooks/post-install.md`](./runbooks/post-install.md).
- Roteer `OPS_AGENT_SECRET` jaarlijks: nieuw secret in `.env` én `/etc/ops-agent/secret`, dan beide herstarten.
- Voeg geen wildcards toe in `sudoers.d/ops-agent` — elke `systemctl`-actie moet een expliciete service-naam zijn.
- `commands.yml` is single source of truth voor wat de agent mag — alles wat niet in de whitelist staat, kan een aanvaller niet uitvoeren ook al heeft hij het secret.