feat(web): dark Gitea UI, systemd installer, WEB-UI docs (W7)

Restyles every template with a hand-written dark Gitea-style theme (web/static/app.css, ~270 lines: badges, buttons, cards, focus rings, prefers-reduced-motion) and completes the htmx polling wiring for all four dashboard cards. Adds the repeatable setup-web-linux.sh installer (idempotent: pip install '[web]' non-editable, render ci-web.service, template [web]/[web.oidc] into config.toml, prompt for keyring secrets, print Gitea OIDC registration steps, enable/restart the unit) plus deploy/systemd/ci-web.service and docs/WEB-UI.md.
2026-07-23 18:36:15 +02:00
parent 43925e6746
commit 60cee5418e
14 changed files with 953 additions and 128 deletions
@@ -0,0 +1,38 @@
+[Unit]
+Description=Local CI/CD — web dashboard (ci web serve)
+Documentation=file:///opt/ci/local-ci-cd-system/docs/WEB-UI.md
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=ci-runner
+Group=ci-runner
+WorkingDirectory=/opt/ci/local-ci-cd-system
+# CI_CONFIG (and any other CI_* override) lives here, one KEY=VALUE per
+# line, no quoting. The "-" prefix means the unit still starts if the file
+# is absent (config.toml is then auto-discovered at /var/lib/ci/config.toml
+# — see config.py's resolution order). Rendered/edited by setup-web-linux.sh
+# — never put secrets in this file, only the config path.
+EnvironmentFile=-/etc/ci/web.env
+# The bind address below is filled in by setup-web-linux.sh at install time
+# (a LAN IP, or left as 127.0.0.1 for loopback-only) — never edit this file
+# by hand on the target host, re-run the installer instead.
+ExecStart=/opt/ci/venv/bin/python -m ci_orchestrator web serve --host __CI_WEB_BIND_HOST__ --port 8800
+Restart=on-failure
+RestartSec=10
+TimeoutStartSec=30s
+
+# Hardening. ProtectHome=read-only (NOT "yes"/true): the OIDC/session
+# secrets are read from ci-runner's headless keyring backend
+# (keyrings.alt.file.PlaintextKeyring, ~/.local/share/python_keyring/ —
+# see docs/WEB-UI.md's keyring-headless note); "yes" would hide /home
+# entirely and every login would fail with a keyring lookup error.
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=read-only
+PrivateTmp=true
+ReadWritePaths=/var/lib/ci
+
+[Install]
+WantedBy=multi-user.target
@@ -0,0 +1,218 @@
+# Web UI — Management Dashboard
+
+Server-rendered dashboard (`ci web serve`) for the local CI/CD system: live
+VMs, cargo cache, disk, and act_runner status, plus confirm-gated destructive
+actions (VM remove/cleanup, cache purge, template backup) with an audit
+trail. In-process only — it imports `operations/` and `backends.load_backend`
+directly and never shells out to the CLI.
+
+See `plans/web-ui-management-plan.md` (steps W0–W7) for the design history
+and `config.example.toml`'s `[web]` / `[web.oidc]` section for every
+config key referenced below.
+
+---
+
+## 1. Prerequisites
+
+- The Linux host already bootstrapped by `setup-host-linux.sh` (`ci-runner`
+  service user, `/opt/ci/venv`, `/var/lib/ci/config.toml`).
+- A reachable Gitea instance to authenticate against (OIDC/OAuth2) — only
+  required if you intend to bind the dashboard on the LAN; a loopback-only
+  install can skip Gitea entirely (see §5, "open mode").
+- Outbound network from the host to Gitea's `/.well-known/openid-configuration`
+  endpoint, if OIDC is enabled.
+
+Nothing here needs internet access — `ci_orchestrator[web]`'s dependencies
+(FastAPI, Jinja2, Authlib, uvicorn, ...) install from the same package index
+already used for the core install, and every frontend asset
+(`web/static/app.css`, `web/static/htmx.min.js`) is vendored in the repo, no
+CDN.
+
+---
+
+## 2. Running the installer
+
+```bash
+cd /opt/ci/local-ci-cd-system
+sudo bash setup-web-linux.sh --host 127.0.0.1        # loopback-only, no OIDC needed
+# or, once OIDC is registered (see §3):
+sudo bash setup-web-linux.sh --host 192.168.1.50      # LAN
+```
+
+`setup-web-linux.sh` is idempotent — every mutating step checks its own
+state first and skips (with a message) when already satisfied, so re-running
+it (e.g. after `git pull` + a code change) is always safe:
+
+1. `pip install '<repo>[web]'` into `/opt/ci/venv`, **non-editable** — per
+   `CLAUDE.md`, the production venv can't resolve editable installs when
+   `act_runner`/systemd launches Python from a transient working directory.
+2. Renders `deploy/systemd/ci-web.service` into `/etc/systemd/system/`,
+   substituting the bind IP you passed via `--host`.
+3. Appends a **commented** `[web]` / `[web.oidc]` template to
+   `/var/lib/ci/config.toml` if no such section exists yet — it never
+   overwrites an existing one, and never writes a secret value.
+4. Prompts (interactively, one at a time) to store `WebSessionSecret` and
+   `WebOidcClientSecret` in the keyring, if they aren't already set. The
+   secret is only ever typed at the terminal prompt — the installer never
+   accepts it as a command-line argument and never echoes or logs it.
+5. Prints the manual Gitea OIDC application registration steps (see §3).
+6. `systemctl daemon-reload` then enables + starts (or restarts, if already
+   running) `ci-web.service`.
+
+Run `setup-web-linux.sh --help` for the full flag list (`--skip-pip`,
+`--skip-secrets`, `--config-path`).
+
+After step 3/4, edit `/var/lib/ci/config.toml`: uncomment the appended
+`[web]` / `[web.oidc]` block, fill in `issuer`, `client_id`,
+`allowed_users`, then restart the service (`systemctl restart ci-web.service`).
+
+---
+
+## 3. Gitea OAuth2 application registration
+
+The dashboard authenticates against Gitea via OIDC (Authlib + Gitea's
+`/.well-known/openid-configuration` discovery document). Register the
+application **before** enabling `[web.oidc]`:
+
+1. In Gitea: **Settings → Applications → "Manage OAuth2 Applications" →
+   Create a new OAuth2 Application**.
+2. **Application Name**: anything recognizable, e.g. `ci-web`.
+3. **Redirect URI**: `http://<LAN-IP>:8800/auth/callback` — this **must
+   match `[web.oidc].redirect_url` exactly** (scheme, host, port, and path).
+   A mismatch is the #1 cause of a login redirect loop (see §6).
+4. Gitea shows a **Client ID** and **Client Secret** exactly once:
+   - Client ID → `[web.oidc].client_id` in `config.toml` (not a secret, plain text is fine).
+   - Client Secret → **never put it in `config.toml`**. Store it in the
+     keyring instead:
+     ```bash
+     sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator creds set \
+         --target WebOidcClientSecret --user web-oidc-client
+     ```
+     `config.toml` only ever holds the keyring *key name*
+     (`client_secret_cred = "WebOidcClientSecret"`), never the value.
+5. Add the Gitea username(s) allowed to log in to `[web].allowed_users`.
+   **The allowlist is fail-closed**: an empty list denies everyone, it
+   never means "allow all".
+
+---
+
+## 4. Operating
+
+```bash
+# Start / stop / restart
+sudo systemctl start ci-web.service
+sudo systemctl stop ci-web.service
+sudo systemctl restart ci-web.service     # after a config.toml edit or a code upgrade
+
+# Status
+systemctl status ci-web.service
+
+# Logs (uvicorn access log + app stdout/stderr go to the journal)
+journalctl -u ci-web.service -f
+journalctl -u ci-web.service -n 100 --no-pager
+
+# Health check (unauthenticated, always 200)
+curl -s http://127.0.0.1:8800/healthz
+```
+
+Once code changes: `sudo bash setup-web-linux.sh --host <same-as-before>`
+reinstalls the `[web]` extra and restarts the service in one step (steps
+2–6 no-op if nothing else changed).
+
+---
+
+## 5. Firewall / security
+
+- **Bind only a specific LAN IP, never `0.0.0.0`.** Neither `ci web serve`
+  nor `setup-web-linux.sh` will ever write `0.0.0.0` — the installer prompts
+  for (or accepts via `--host`) one explicit address, defaulting to
+  `127.0.0.1`.
+- **Open mode (no `[web.oidc]` configured) is localhost-only, enforced at
+  startup.** `ci web serve` refuses to start if you bind a non-loopback
+  address while `[web.oidc]` is absent — an unauthenticated dashboard that
+  can destroy VMs and purge caches must never be reachable from the LAN.
+  Configure `[web.oidc]` first, or bind `127.0.0.1`.
+- Every mutating route (VM remove/cleanup, cache purge, template backup) is
+  behind a synchronizer-token CSRF check and a two-step confirm gate (a
+  preview/dry-run, then an explicit "Confirm" that actually executes) —
+  there is no one-click destroy.
+- Every mutating action appends exactly one entry to the audit log
+  (`[web].audit_log`, default `/var/lib/ci/logs/web-audit.jsonl`), viewable
+  at `/audit` in the dashboard.
+- If you run a host firewall (ufw/nftables/iptables), only open the chosen
+  port (default `8800`) to the specific LAN/VLAN that needs dashboard
+  access, not the whole network.
+
+---
+
+## 6. Keyring / headless note
+
+`ci-web.service` runs as `ci-runner` under systemd — there is no desktop
+session and no D-Bus, so the GNOME Secret Service backend (`secret-tool`)
+does not work here. This host uses **`keyrings.alt.file.PlaintextKeyring`**
+instead (already the credential backend used for guest/Gitea credentials —
+see `plans/archived/2026-05-23/B3-closeout.md`):
+
+- Config: `/home/ci-runner/.local/share/python_keyring/keyringrc.cfg`
+  (`[backend] default-keyring=keyrings.alt.file.PlaintextKeyring`)
+- Store: `/home/ci-runner/.local/share/python_keyring/keyring_pass.cfg` —
+  plain text, readable only by `ci-runner` (file permissions), no D-Bus
+  session required. Verified to work both from `sudo -u ci-runner ...` and
+  from inside a plain systemd service.
+- This is why `ci-web.service`'s hardening uses `ProtectHome=read-only`
+  and **not** `ProtectHome=yes`/`true`: the latter hides `/home` entirely
+  from the unit's mount namespace, which would break every OIDC/session
+  secret lookup and make login fail even though the keyring itself is
+  fine. `read-only` keeps `/home/ci-runner` readable (the app never writes
+  to the keyring at request time — secrets are set once, out-of-band, by
+  `ci creds set`) while still blocking writes.
+- `WebSessionSecret` / `WebOidcClientSecret` are keyring key *names* in
+  `config.toml` (`session_secret_cred`, `client_secret_cred`) — the actual
+  values live only in the keyring, set via `ci creds set --target <name>
+  --user <label>` (interactive prompt, `hide_input` + confirmation; never
+  a CLI argument, never logged).
+
+---
+
+## 7. Troubleshooting
+
+**Login loop (bounces back to `/login` after authenticating with Gitea)**
+: The registered Redirect URI in Gitea does not exactly match
+  `[web.oidc].redirect_url` in `config.toml` — check scheme (`http` vs
+  `https`), host/IP, port, and the `/auth/callback` path character-for-character.
+
+**403 after a successful Gitea login**
+: Your Gitea username is not in `[web].allowed_users` (or the list is
+  empty — the allowlist is fail-closed by design). Add it and restart the
+  service.
+
+**"keyring key '...' not found -- run `ci creds set ...`" in the journal /
+on `/login`**
+: The session secret or the OIDC client secret has not been stored yet
+  (or was stored for a different Unix user than `ci-runner`, or under a
+  different `_cred` name than the one in `config.toml`). Re-run:
+  ```bash
+  sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator creds set \
+      --target WebSessionSecret --user web-session
+  ```
+  substituting the exact key name printed in the error. See §6 for why this
+  must run as `ci-runner`, not as your own login.
+
+**Dashboard is blank / cards show "unavailable"**
+: The VM backend (`vmrun`) or `shutil.disk_usage`/`systemctl` could not be
+  reached from the host — the dashboard degrades a card to an "unavailable"
+  notice instead of a 500. Check `vmware-host.service` is up
+  (`systemctl is-active vmware-host.service`) and that `/healthz` still
+  returns `200`.
+
+**`ci web serve` refuses to start with "refusing to bind ... without
+authentication"**
+: You passed a non-loopback `--host` (or `[web].bind_host` in
+  `config.toml`) while `[web.oidc]` is unset. This is the guard described
+  in §5 — configure `[web.oidc]` (see §3) or bind `127.0.0.1`.
+
+**Confirm/Cleanup/Purge form returns 403**
+: The CSRF token expired (the session cookie was cleared, e.g. by
+  `/logout`, or the browser tab was left open across a service restart
+  that rotated the session secret in open mode). Reload the page and retry
+  — the confirm form always mints a fresh token.
@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+# setup-web-linux.sh — install/upgrade the ci-orchestrator web dashboard (W7b)
+#
+# Repeatable / idempotent: safe to re-run any time (e.g. after `git pull` +
+# a code change — see CLAUDE.md: the production venv must be reinstalled
+# non-editable after every change). Every mutating step checks its own
+# state first and skips (with a message) when already satisfied.
+#
+# What it does:
+#   1. pip install '<repo>[web]' into /opt/ci/venv, non-editable, as ci-runner
+#   2. Render deploy/systemd/ci-web.service into /etc/systemd/system/,
+#      substituting the LAN bind IP; write /etc/ci/web.env (CI_CONFIG) if the
+#      config path was overridden
+#   3. Ensure a commented [web]/[web.oidc] template exists in config.toml
+#      (never overwrites an existing [web] section)
+#   4. Prompt to store WebSessionSecret / WebOidcClientSecret in the keyring
+#      (interactive prompt only — never accepts a secret as a CLI argument)
+#   5. Print the manual Gitea OIDC application registration steps
+#   6. systemctl daemon-reload && enable (+ restart if already running)
+#
+# Usage: sudo bash setup-web-linux.sh [--host <lan-ip>] [options]
+# See --help for the full option list.
+
+set -euo pipefail
+
+# ── Defaults ─────────────────────────────────────────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CI_USER="ci-runner"
+OPT_CI="/opt/ci"
+VENV="$OPT_CI/venv"
+REPO_DIR="$SCRIPT_DIR"
+UNIT_SRC="$REPO_DIR/deploy/systemd/ci-web.service"
+UNIT_DST="/etc/systemd/system/ci-web.service"
+ENV_FILE="/etc/ci/web.env"
+CONFIG_PATH="/var/lib/ci/config.toml"
+WEB_PORT=8800
+WEB_HOST=""            # resolved below (arg > prompt > 127.0.0.1)
+SKIP_PIP=false
+SKIP_SECRETS=false
+ASSUME_DEFAULT_HOST=false
+
+# ── Colours ──────────────────────────────────────────────────────────────────
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+info()  { echo -e "${GREEN}==>${NC} $*"; }
+warn()  { echo -e "${YELLOW}  ! $*${NC}"; }
+die()   { echo -e "${RED}ERROR: $*${NC}" >&2; exit 1; }
+
+usage() {
+    cat <<EOF
+Usage: sudo bash $(basename "$0") [options]
+
+Options:
+  --host <ip>         LAN IP the dashboard binds to (written into the unit
+                       and into the config.toml template). Default: prompt,
+                       falling back to 127.0.0.1 (loopback-only) on Enter.
+  --config-path <p>    Target config.toml (default: $CONFIG_PATH).
+  --skip-pip            Skip step 1 (pip install '[web]' extra).
+  --skip-secrets         Skip step 4 (interactive keyring secret prompts).
+  -h, --help              Show this help.
+
+Never binds 0.0.0.0. Binding a non-loopback IP without [web.oidc]
+configured is refused at runtime by 'ci web serve' itself (open mode is
+localhost-only) -- see docs/WEB-UI.md.
+
+Examples:
+  sudo bash setup-web-linux.sh --host 127.0.0.1
+  sudo bash setup-web-linux.sh --host 192.168.1.50
+  sudo bash setup-web-linux.sh --skip-pip --skip-secrets   # re-render unit only
+EOF
+    exit 1
+}
+
+# ── Parse args ───────────────────────────────────────────────────────────────
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --host) WEB_HOST="$2"; shift 2 ;;
+        --config-path) CONFIG_PATH="$2"; shift 2 ;;
+        --skip-pip) SKIP_PIP=true; shift ;;
+        --skip-secrets) SKIP_SECRETS=true; shift ;;
+        -h|--help) usage ;;
+        *) echo "Unknown option: $1" >&2; usage ;;
+    esac
+done
+
+[[ $EUID -eq 0 ]] || die "run as root (sudo bash $(basename "$0") ...)"
+[[ -f "$UNIT_SRC" ]] || die "unit template not found: $UNIT_SRC (run from the repo root)"
+id "$CI_USER" &>/dev/null || die "user '$CI_USER' does not exist -- run setup-host-linux.sh first"
+[[ -x "$VENV/bin/python" ]] || die "$VENV/bin/python not found -- run setup-host-linux.sh first"
+
+if [[ -z "$WEB_HOST" ]]; then
+    read -r -p "LAN IP to bind the dashboard to [127.0.0.1]: " WEB_HOST
+    WEB_HOST="${WEB_HOST:-127.0.0.1}"
+fi
+
+echo ""
+echo "╔══════════════════════════════════════════════════════╗"
+echo "║        ci-orchestrator web dashboard — installer      ║"
+echo "╚══════════════════════════════════════════════════════╝"
+echo "  Bind        : ${WEB_HOST}:${WEB_PORT}"
+echo "  ci_user     : $CI_USER"
+echo "  venv        : $VENV"
+echo "  config.toml : $CONFIG_PATH"
+echo ""
+
+# ── Step 1: pip install '[web]' extra (non-editable, per CLAUDE.md) ─────────
+if [[ "$SKIP_PIP" == false ]]; then
+    info "[1/6] Installing ci_orchestrator[web] into $VENV (non-editable)"
+    sudo -u "$CI_USER" "$VENV/bin/pip" install -q "${REPO_DIR}[web]"
+    verify_out=$(sudo -u "$CI_USER" "$VENV/bin/python" -m ci_orchestrator web serve --help 2>&1) \
+        || die "'ci web serve --help' failed after install -- see output above"
+    echo "  Verify OK: ${verify_out%%$'\n'*}"
+else
+    info "[1/6] pip install -- SKIPPED (--skip-pip)"
+fi
+
+# ── Step 2: render the systemd unit + optional CI_CONFIG env file ───────────
+info "[2/6] Rendering ci-web.service (bind host: $WEB_HOST)"
+RENDERED="$(mktemp)"
+trap 'rm -f "$RENDERED"' EXIT
+sed "s#__CI_WEB_BIND_HOST__#${WEB_HOST}#" "$UNIT_SRC" > "$RENDERED"
+
+if [[ -f "$UNIT_DST" ]] && cmp -s "$RENDERED" "$UNIT_DST"; then
+    warn "$UNIT_DST already up to date -- skip"
+    UNIT_CHANGED=false
+else
+    install -m 644 "$RENDERED" "$UNIT_DST"
+    echo "  Wrote $UNIT_DST"
+    UNIT_CHANGED=true
+fi
+
+mkdir -p /etc/ci
+if [[ "$CONFIG_PATH" != "/var/lib/ci/config.toml" ]]; then
+    if [[ -f "$ENV_FILE" ]] && grep -q '^CI_CONFIG=' "$ENV_FILE"; then
+        warn "$ENV_FILE already sets CI_CONFIG -- skip (edit manually to change it)"
+    else
+        echo "CI_CONFIG=$CONFIG_PATH" >> "$ENV_FILE"
+        chmod 640 "$ENV_FILE"
+        chown "root:$CI_USER" "$ENV_FILE" 2>/dev/null || true
+        echo "  Wrote CI_CONFIG=$CONFIG_PATH to $ENV_FILE"
+    fi
+else
+    echo "  Using the auto-discovered default config.toml path -- no $ENV_FILE needed"
+fi
+
+# ── Step 3: ensure a [web]/[web.oidc] template exists in config.toml ────────
+info "[3/6] config.toml [web] / [web.oidc] template"
+WEB_MARKER="# --- appended by setup-web-linux.sh ---"
+if [[ -f "$CONFIG_PATH" ]] && { grep -qF "$WEB_MARKER" "$CONFIG_PATH" || grep -q '^\[web\]' "$CONFIG_PATH"; }; then
+    warn "[web] section (or a previously appended template) already present in $CONFIG_PATH -- skip, not overwriting"
+else
+    [[ -f "$CONFIG_PATH" ]] || die "$CONFIG_PATH does not exist -- run setup-host-linux.sh first (it creates the base config.toml)"
+    cat >> "$CONFIG_PATH" <<EOF
+
+$WEB_MARKER
+# Uncomment and fill in [web.oidc] once you have registered the Gitea
+# OAuth2 application (see the installer's step 5 output / docs/WEB-UI.md).
+# session_secret_cred / client_secret_cred are KEYRING KEY NAMES only --
+# the secrets themselves are never written to this file.
+#
+# [web]
+# enabled             = true
+# bind_host           = "${WEB_HOST}"   # never 0.0.0.0
+# bind_port           = ${WEB_PORT}
+# audit_log           = "/var/lib/ci/logs/web-audit.jsonl"
+# allowed_users       = ["CHANGE-ME"]     # Gitea usernames allowed to log in
+# session_secret_cred = "WebSessionSecret"
+#
+# [web.oidc]
+# issuer              = "https://CHANGE-ME.example"
+# client_id           = "CHANGE-ME"
+# redirect_url        = "http://${WEB_HOST}:${WEB_PORT}/auth/callback"
+# client_secret_cred  = "WebOidcClientSecret"
+# scopes              = ["openid", "profile"]
+EOF
+    echo "  Appended a commented [web]/[web.oidc] template to $CONFIG_PATH"
+fi
+
+# ── Step 4: keyring secrets (interactive prompt only, never argv) ───────────
+info "[4/6] Keyring secrets (WebSessionSecret, WebOidcClientSecret)"
+if [[ "$SKIP_SECRETS" == true ]]; then
+    echo "  SKIPPED (--skip-secrets)"
+else
+    _secret_present() {
+        sudo -u "$CI_USER" "$VENV/bin/python" -c "
+from ci_orchestrator.credentials import KeyringCredentialStore
+KeyringCredentialStore().get('$1')
+" &>/dev/null
+    }
+
+    _set_secret_if_needed() {
+        local name="$1" label="$2"
+        if _secret_present "$name"; then
+            warn "Keyring key '$name' already set -- skip"
+            return
+        fi
+        read -r -p "  Set keyring key '$name' now? [Y/n] " ans
+        case "$ans" in
+            [nN]*)
+                warn "Skipped -- set it later with:" \
+                     "sudo -u $CI_USER $VENV/bin/python -m ci_orchestrator creds set --target $name --user $label"
+                ;;
+            *)
+                # Delegates straight to the CLI's own interactive prompt
+                # (hide_input + confirmation) -- the secret never touches
+                # this script's variables, argv, or any log.
+                sudo -u "$CI_USER" "$VENV/bin/python" -m ci_orchestrator creds set \
+                    --target "$name" --user "$label"
+                ;;
+        esac
+    }
+
+    _set_secret_if_needed "WebSessionSecret" "web-session"
+    _set_secret_if_needed "WebOidcClientSecret" "web-oidc-client"
+fi
+
+# ── Step 5: manual Gitea OIDC app registration instructions ─────────────────
+info "[5/6] Gitea OIDC application registration (manual step)"
+cat <<EOF
+
+  In Gitea: Settings -> Applications -> "Manage OAuth2 Applications" -> Create
+    Application name : ci-web
+    Redirect URI      : http://${WEB_HOST}:${WEB_PORT}/auth/callback
+                          (must match [web.oidc].redirect_url EXACTLY --
+                          host, port and path, or login will loop)
+
+  After creating it, Gitea shows a Client ID and Client Secret ONCE:
+    1. Client ID     -> set [web.oidc].client_id in $CONFIG_PATH
+    2. Client Secret -> store in the keyring (never in config.toml):
+         sudo -u $CI_USER $VENV/bin/python -m ci_orchestrator creds set \\
+             --target WebOidcClientSecret --user web-oidc-client
+    3. Add your Gitea username(s) to [web].allowed_users in $CONFIG_PATH
+    4. Uncomment [web] and [web.oidc] in $CONFIG_PATH
+
+EOF
+
+# ── Step 6: enable + (re)start the service ───────────────────────────────────
+info "[6/6] systemctl daemon-reload + enable/restart ci-web.service"
+systemctl daemon-reload
+if systemctl is-active --quiet ci-web.service; then
+    systemctl restart ci-web.service
+    echo "  ci-web.service was already running -- restarted to pick up any changes"
+else
+    systemctl enable --now ci-web.service
+    echo "  ci-web.service enabled and started"
+fi
+
+echo ""
+echo "╔══════════════════════════════════════════════════════╗"
+echo "║                 Install complete                     ║"
+echo "╚══════════════════════════════════════════════════════╝"
+echo ""
+echo "  Status : systemctl status ci-web.service"
+echo "  Logs   : journalctl -u ci-web.service -f"
+if [[ "$WEB_HOST" == "127.0.0.1" || "$WEB_HOST" == "localhost" ]]; then
+    echo "  URL    : http://${WEB_HOST}:${WEB_PORT}/ (loopback only -- open mode works without OIDC)"
+else
+    echo "  URL    : http://${WEB_HOST}:${WEB_PORT}/"
+    echo "  NOTE   : a LAN bind refuses to start until [web.oidc] is configured"
+    echo "           and enabled in $CONFIG_PATH (see step 5 above) -- this"
+    echo "           matches the same guard 'ci web serve' enforces itself."
+fi
+echo "  Docs   : $REPO_DIR/docs/WEB-UI.md"
+echo ""
@@ -1 +1,262 @@
-/* placeholder -- real dark Gitea-style design tokens land in W7 */
+/* ci-orchestrator web dashboard — dark, Gitea-style theme (W7a).
+ *
+ * Hand-written, no external framework. Design tokens per the W7 plan
+ * (plans/web-ui-management-plan.md, section W7a). Everything under this
+ * directory is served locally (`/static/app.css`) — the host LAN may be
+ * offline, so no `@import url(...)` to a CDN, no remote fonts.
+ */
+
+:root {
+  --bg: #16191d;
+  --panel: #1c2126;
+  --panel-2: #22272e;
+  --border: #30363d;
+  --text: #d1d5da;
+  --text-dim: #8b949e;
+  --accent: #3fb950;
+  --accent-hover: #46c359;
+  --danger: #f85149;
+  --warn: #d29922;
+  --link: #58a6ff;
+  --radius: 6px;
+  --font: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
+/* ── reset ────────────────────────────────────────────────────────────── */
+
+*, *::before, *::after { box-sizing: border-box; }
+
+html, body {
+  margin: 0;
+  padding: 0;
+  background: var(--bg);
+  color: var(--text);
+  font-family: var(--font);
+  font-size: 15px;
+  line-height: 1.5;
+}
+
+h1, h2, h3, p, dl, dd { margin: 0 0 0.75rem; }
+
+a { color: var(--link); text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+code, .mono {
+  font-family: var(--mono);
+  font-size: 0.9em;
+  background: var(--panel-2);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  padding: 0.05em 0.4em;
+  color: var(--text);
+}
+
+/* ── navbar ───────────────────────────────────────────────────────────── */
+
+.navbar {
+  background: var(--panel);
+  border-bottom: 1px solid var(--border);
+}
+
+.navbar-inner {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 0.85rem 1.5rem;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  flex-wrap: wrap;
+}
+
+.navbar-brand {
+  color: var(--text);
+  font-weight: 600;
+  font-size: 1.05rem;
+}
+.navbar-brand:hover { color: var(--accent-hover); text-decoration: none; }
+
+.navbar-links {
+  display: flex;
+  align-items: center;
+  gap: 1.25rem;
+  font-size: 0.9rem;
+}
+.navbar-links a { color: var(--text-dim); }
+.navbar-links a:hover { color: var(--link); }
+
+.navbar-user { color: var(--text); font-weight: 500; }
+.navbar-user-local { color: var(--text-dim); font-style: italic; }
+.navbar-logout { color: var(--danger) !important; }
+
+/* ── layout ───────────────────────────────────────────────────────────── */
+
+.content { max-width: 1200px; margin: 0 auto; padding: 1.5rem; }
+
+.dashboard-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+  gap: 1.25rem;
+  align-items: start;
+}
+
+/* A polling wrapper (htmx hx-get/hx-trigger target) that must not itself
+ * become a grid box — its children (the real .card sections) lay out
+ * directly in the parent grid. */
+.contents { display: contents; }
+
+/* ── cards ────────────────────────────────────────────────────────────── */
+
+.card {
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 1.25rem;
+}
+
+.card h2 {
+  font-size: 0.85rem;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--text-dim);
+  border-bottom: 1px solid var(--border);
+  padding-bottom: 0.6rem;
+  margin-bottom: 0.9rem;
+}
+
+.card h3 { font-size: 0.95rem; color: var(--text); }
+
+/* ── definition lists (status cards) ─────────────────────────────────── */
+
+dl { display: grid; grid-template-columns: auto 1fr; gap: 0.35rem 0.9rem; }
+dt { color: var(--text-dim); font-weight: 500; }
+dd { margin: 0; }
+
+/* ── tables ───────────────────────────────────────────────────────────── */
+
+.table-wrap { overflow-x: auto; }
+
+table { width: 100%; border-collapse: collapse; font-size: 0.9rem; }
+
+th, td { text-align: left; padding: 0.5rem 0.6rem; border-bottom: 1px solid var(--border); }
+
+th {
+  color: var(--text-dim);
+  font-weight: 600;
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+
+tbody tr { transition: background-color 120ms ease; }
+tbody tr:hover { background: var(--panel-2); }
+
+tr.row-orphan td { color: var(--warn); }
+tr.row-alert td { color: var(--danger); }
+
+/* ── status badges ────────────────────────────────────────────────────── */
+
+.badge {
+  display: inline-block;
+  padding: 0.15rem 0.6rem;
+  border-radius: 999px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  line-height: 1.5;
+  white-space: nowrap;
+}
+
+.badge-success { background: rgba(63, 185, 80, 0.15); color: var(--accent); border: 1px solid rgba(63, 185, 80, 0.4); }
+.badge-danger  { background: rgba(248, 81, 73, 0.15); color: var(--danger); border: 1px solid rgba(248, 81, 73, 0.4); }
+.badge-warn    { background: rgba(210, 153, 34, 0.15); color: var(--warn); border: 1px solid rgba(210, 153, 34, 0.4); }
+
+/* ── buttons ──────────────────────────────────────────────────────────── */
+
+.btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  border: 1px solid transparent;
+  border-radius: var(--radius);
+  padding: 0.45rem 0.9rem;
+  font-size: 0.875rem;
+  font-weight: 600;
+  font-family: inherit;
+  cursor: pointer;
+  background: var(--panel-2);
+  color: var(--text);
+  transition: background-color 120ms ease, border-color 120ms ease, transform 80ms ease;
+}
+.btn:hover { background: var(--border); }
+.btn:active { transform: translateY(1px); }
+
+.btn-primary { background: var(--accent); color: #04170a; border-color: var(--accent); }
+.btn-primary:hover { background: var(--accent-hover); }
+
+.btn-danger { background: transparent; color: var(--danger); border-color: var(--danger); }
+.btn-danger:hover { background: var(--danger); color: #2b0705; }
+
+/* ── forms ────────────────────────────────────────────────────────────── */
+
+form { margin-top: 1rem; display: flex; flex-wrap: wrap; align-items: center; gap: 0.75rem; }
+
+label { font-size: 0.85rem; color: var(--text-dim); display: inline-flex; align-items: center; gap: 0.4rem; }
+
+input[type="text"], input[type="number"] {
+  background: var(--panel-2);
+  border: 1px solid var(--border);
+  color: var(--text);
+  border-radius: var(--radius);
+  padding: 0.4rem 0.6rem;
+  font-size: 0.875rem;
+  font-family: inherit;
+}
+
+/* ── notices / confirm / result panels ───────────────────────────────── */
+
+.notice {
+  border-radius: var(--radius);
+  padding: 0.75rem 1rem;
+  margin: 0.75rem 0;
+  border: 1px solid var(--border);
+  font-size: 0.9rem;
+}
+.notice-warn { background: rgba(210, 153, 34, 0.08); border-color: rgba(210, 153, 34, 0.4); color: var(--warn); }
+
+.confirm-box { margin-bottom: 1.25rem; }
+
+.action-result {
+  border-radius: var(--radius);
+  padding: 0.9rem 1.1rem;
+  margin-bottom: 1.25rem;
+  border: 1px solid var(--border);
+}
+.result-ok { border-color: rgba(63, 185, 80, 0.4); background: rgba(63, 185, 80, 0.08); }
+.result-error { border-color: rgba(248, 81, 73, 0.4); background: rgba(248, 81, 73, 0.08); }
+
+/* ── accessibility ────────────────────────────────────────────────────── */
+
+:focus-visible {
+  outline: 2px solid var(--link);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.001ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.001ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* ── responsive ───────────────────────────────────────────────────────── */
+
+@media (max-width: 640px) {
+  .navbar-inner { flex-direction: column; align-items: flex-start; gap: 0.5rem; }
+  form { flex-direction: column; align-items: flex-start; }
+  dl { grid-template-columns: 1fr; }
+}
@@ -8,9 +8,20 @@
  <script src="/static/htmx.min.js" defer></script>
 </head>
 <body>
+  {% set logged_in_user = request.session.get("user") %}
  <nav class="navbar">
-    <span class="navbar-brand">ci-orchestrator</span>
+    <div class="navbar-inner">
+      <a class="navbar-brand" href="/">ci-orchestrator</a>
+      <div class="navbar-links">
        <a href="/audit">Audit log</a>
+        {% if logged_in_user %}
+        <span class="navbar-user" aria-label="Logged in as {{ logged_in_user }}">{{ logged_in_user }}</span>
+        <a class="navbar-logout" href="/logout" aria-label="Log out">Logout</a>
+        {% else %}
+        <span class="navbar-user navbar-user-local">local</span>
+        {% endif %}
+      </div>
+    </div>
  </nav>
  <main class="content">
    {% block content %}{% endblock %}
@@ -3,13 +3,9 @@
 {% block title %}Dashboard - ci-orchestrator{% endblock %}

 {% block content %}
-<section class="card" id="vms-card">
+<div class="dashboard-grid">
  {% include "partials/vms.html" %}
-</section>
-
-<section class="card" id="cache-card">
  {% include "partials/cache.html" %}
-</section>
-
  {% include "partials/host.html" %}
+</div>
 {% endblock %}
@@ -6,6 +6,7 @@
 <section class="card" id="audit-card">
  <h2>Audit log</h2>
  {% if entries %}
+  <div class="table-wrap">
    <table>
      <thead>
        <tr>
@@ -24,12 +25,21 @@
          <td>{{ e.user }}</td>
          <td>{{ e.action }}</td>
          <td><code>{{ e.target }}</code></td>
-        <td>{{ e.result }}</td>
+          <td>
+            {% if e.result == "ok" %}
+            <span class="badge badge-success">ok</span>
+            {% elif e.result == "error" %}
+            <span class="badge badge-danger">error</span>
+            {% else %}
+            <span class="badge badge-warn">{{ e.result }}</span>
+            {% endif %}
+          </td>
          <td>{{ e.detail }}</td>
        </tr>
        {% endfor %}
      </tbody>
    </table>
+  </div>
  {% else %}
  <p>No audit entries yet.</p>
  {% endif %}
@@ -1,4 +1,4 @@
-<div id="cache-partial">
+<section class="card" id="cache-card" hx-get="/cache" hx-trigger="every 5s" hx-swap="outerHTML">
  <h2>Cargo cache</h2>
  {% if cache %}
  <dl>
@@ -10,10 +10,10 @@
    <dt>Retention</dt><dd>{{ cache.retention_days }} day(s)</dd>
  </dl>
  {% else %}
-  <p class="notice notice-warn">Cargo cache status unavailable.</p>
+  <p class="notice notice-warn" role="alert">Cargo cache status unavailable.</p>
  {% endif %}
-  <form method="post" action="/cache/purge" id="cache-purge-form">
+  <form method="post" action="/cache/purge" id="cache-purge-form" aria-label="Purge cargo cache">
    <input type="hidden" name="csrf" value="{{ csrf_token }}">
-    <button type="submit" class="btn btn-danger">Purge cache</button>
+    <button type="submit" class="btn btn-danger" aria-label="Purge cargo cache">Purge cache</button>
  </form>
-</div>
+</section>
@@ -1,4 +1,4 @@
-<div class="confirm-box notice notice-warn" id="action-confirm">
+<div class="confirm-box notice notice-warn" id="action-confirm" role="alert">
  <h3>Confirm: {{ action_label }}</h3>
  <p>Target: <code>{{ target }}</code></p>
  <p>{{ summary }}</p>
@@ -8,6 +8,6 @@
    {% for key, value in extra_fields.items() %}
    <input type="hidden" name="{{ key }}" value="{{ value }}">
    {% endfor %}
-    <button type="submit" class="btn btn-danger">Confirm</button>
+    <button type="submit" class="btn btn-danger" aria-label="Confirm: {{ action_label }}">Confirm</button>
  </form>
 </div>
@@ -1,3 +1,4 @@
+<div class="contents" id="host-partial" hx-get="/host" hx-trigger="every 5s" hx-swap="outerHTML">
  <section class="card" id="disk-card">
    <h2>Disk</h2>
    {% if disk %}
@@ -8,41 +9,51 @@
      <dt>Used</dt><dd>{{ "%.1f"|format(disk.used_pct) }}%</dd>
    </dl>
    {% else %}
-  <p class="notice notice-warn">Disk status unavailable.</p>
+    <p class="notice notice-warn" role="alert">Disk status unavailable.</p>
    {% endif %}
  </section>

  <section class="card" id="runner-card">
    <h2>Runners</h2>
    {% if runners %}
+    <div class="table-wrap">
      <table>
        <thead>
          <tr>
            <th>Service</th>
-        <th>Active</th>
+            <th>Status</th>
            <th>Sub-state</th>
          </tr>
        </thead>
        <tbody>
          {% for runner in runners %}
-      <tr class="{{ 'row-ok' if runner.active else 'row-alert' }}">
+          <tr class="{{ 'row-alert' if not runner.active else '' }}">
            <td>{{ runner.name }}</td>
-        <td>{{ "yes" if runner.active else "no" }}</td>
+            <td>
+              {% if runner.active %}
+              <span class="badge badge-success">active</span>
+              {% else %}
+              <span class="badge badge-danger">down</span>
+              {% endif %}
+            </td>
            <td>{{ runner.sub_state }}</td>
          </tr>
          {% endfor %}
        </tbody>
      </table>
+    </div>
    {% else %}
-  <p class="notice notice-warn">Runner status unavailable.</p>
+    <p class="notice notice-warn" role="alert">Runner status unavailable.</p>
    {% endif %}
  </section>

  <section class="card" id="backup-card">
    <h2>Template backup</h2>
-  <form method="post" action="/host/backup" id="host-backup-form">
+    <form method="post" action="/host/backup" id="host-backup-form" aria-label="Backup template">
      <input type="hidden" name="csrf" value="{{ csrf_token }}">
-    <label>Template: <input type="text" name="template" required></label>
-    <button type="submit" class="btn btn-danger">Backup template</button>
+      <label for="host-backup-template">Template</label>
+      <input type="text" id="host-backup-template" name="template" required>
+      <button type="submit" class="btn btn-danger" aria-label="Backup template">Backup template</button>
    </form>
  </section>
+</div>
@@ -1,5 +1,5 @@
-<div class="notice notice-warn" id="action-lock-conflict">
-  <h3>{{ action_label }} refused</h3>
+<div class="notice notice-warn" id="action-lock-conflict" role="alert">
+  <h3>{{ action_label }} refused <span class="badge badge-warn">locked</span></h3>
  <p>A job may be running against <code>{{ target }}</code> (a fresh
     <code>vm-start.lock</code> is present). Try again once it clears.</p>
 </div>
@@ -1,4 +1,11 @@
-<div class="action-result {{ 'result-ok' if ok else 'result-error' }}" id="action-result">
-  <h3>{{ action_label }} -- {{ "ok" if ok else "error" }}</h3>
+<div class="action-result {{ 'result-ok' if ok else 'result-error' }}" id="action-result" role="status" aria-live="polite">
+  <h3>
+    {{ action_label }} --
+    {% if ok %}
+    <span class="badge badge-success">ok</span>
+    {% else %}
+    <span class="badge badge-danger">error</span>
+    {% endif %}
+  </h3>
  <p>{{ detail }}</p>
 </div>
@@ -1,9 +1,10 @@
-<div id="vms-partial" hx-get="/vms" hx-trigger="every 5s" hx-swap="outerHTML">
+<section class="card" id="vms-card" hx-get="/vms" hx-trigger="every 5s" hx-swap="outerHTML">
  <h2>Live VMs</h2>
  {% if not backend_available %}
-  <p class="notice notice-warn">Backend unavailable (vmrun not found on this host).</p>
+  <p class="notice notice-warn" role="alert">Backend unavailable (vmrun not found on this host).</p>
  {% endif %}
  {% if vms %}
+  <div class="table-wrap">
    <table>
      <thead>
        <tr>
@@ -12,7 +13,7 @@
          <th>IP</th>
          <th>Guest OS</th>
          <th>Uptime (s)</th>
-        <th>Orphan?</th>
+          <th>Status</th>
          <th>Actions</th>
        </tr>
      </thead>
@@ -24,23 +25,31 @@
          <td>{{ vm.ip or "-" }}</td>
          <td>{{ vm.guest_os or "-" }}</td>
          <td>{{ vm.uptime_sec if vm.uptime_sec is not none else "-" }}</td>
-        <td>{{ "yes" if vm.is_orphan else "no" }}</td>
+          <td>
+            {% if vm.is_orphan %}
+            <span class="badge badge-warn">orphan</span>
+            {% else %}
+            <span class="badge badge-success">running</span>
+            {% endif %}
+          </td>
          <td>
            <form method="post" action="/vms/{{ vm.vmx | vmx_id }}/remove">
              <input type="hidden" name="csrf" value="{{ csrf_token }}">
-            <button type="submit" class="btn btn-danger">Remove</button>
+              <button type="submit" class="btn btn-danger" aria-label="Remove VM {{ vm.name }}">Remove</button>
            </form>
          </td>
        </tr>
        {% endfor %}
      </tbody>
    </table>
+  </div>
  {% else %}
  <p>No VMs currently running.</p>
  {% endif %}
-  <form method="post" action="/vms/cleanup" id="vms-cleanup-form">
+  <form method="post" action="/vms/cleanup" id="vms-cleanup-form" aria-label="Cleanup orphaned VMs">
    <input type="hidden" name="csrf" value="{{ csrf_token }}">
-    <label>Max age (h): <input type="number" name="max_age_hours" value="4" min="0"></label>
-    <button type="submit" class="btn btn-danger">Cleanup orphans</button>
+    <label for="vms-cleanup-max-age">Max age (h)</label>
+    <input type="number" id="vms-cleanup-max-age" name="max_age_hours" value="4" min="0">
+    <button type="submit" class="btn btn-danger" aria-label="Cleanup orphaned VMs older than the given age">Cleanup orphans</button>
  </form>
-</div>
+</section>