docs(vault): fleet-wide fact re-verification pass (67 pages)
The docs-fact census wave re-read the live hosts and re-keyed every page it could: runtime/payload identities, ports, sizes, ledger figures, unit state, and the retirement banners that drifted as the fleet moved. The wave was interrupted mid-run, so this commit carries only what passed the integrity gates: every touched page parses (front matter or H1+status convention intact, balanced fences, no truncated tables, trailing newline), the docs_completeness and link-integrity seams are green, and bats is 384/384. Numbers that this session proved on live hosts are keyed to the measured value, not the page's earlier claim.
This commit is contained in:
Frank
@@ -5,7 +5,7 @@ tags:
|
||||
- architecture
|
||||
- e2e
|
||||
- homepage
|
||||
timestamp: 2026-09-01
|
||||
timestamp: 2026-10-18
|
||||
---
|
||||
|
||||
# E2E Suite — homepage + guard chain (Playwright)
|
||||
@@ -28,16 +28,21 @@ user sees it; the `bats` seams assert config shape, not behavior.
|
||||
| `specs/19-frankbook.spec.ts` | `frankbook` project: walks the six admin links that terminate on FrankBook-Pro (192.168.0.112) — conditional, see below |
|
||||
| `specs/13-sso.spec.ts` | direct guarded-vhost visits resolve silently with ONLY the homepage session (single-login enforcement) |
|
||||
| `specs/14-guard.spec.ts` | `guest` project, no storage state: unauthenticated traffic lands on the IdP login |
|
||||
| `specs/15-unauth-fetch.spec.ts` | `guest` project: a wget-style client must never receive application bytes from a guarded service — it asserts on **leakage** (app-code markers), not on status code |
|
||||
| `specs/16-marreta.spec.ts` | regression guard for the 2026-09-12 incident: the marreta tile resolving to the authentik login flow because the `marreta-proxy` ProxyProvider had no linked Application |
|
||||
| `specs/17-hermes-vhost.spec.ts` | `hermes.franksdank.cloud` fronts a host-networked container, so the vhost upstream is the host LAN address; guards the 2026-09-16 loopback-bind 502 that the rest of the suite stayed green through |
|
||||
| `specs/18-openwebui-sso.spec.ts` | `ai.franksdank.cloud` completes its OIDC round-trip silently with only the homepage session |
|
||||
| `lib/login.ts` | `akLogin` helper (two-stage flow, shadow-DOM locators) |
|
||||
| `lib/env.ts` | loads `.env.local`, exports `REAL_UA` |
|
||||
| `tests/e2e_scaffold.bats` | bats seam: structure + no-credentials-tracked (never drives the fleet) |
|
||||
| `tests/e2e_scaffold.bats` | bats seam: structure, placeholder-only example env, **every spec matched by a playwright project** (`tests/e2e_scaffold.bats:51`), and no credentials/auth state tracked. Never drives the fleet |
|
||||
|
||||
## Projects and auth
|
||||
|
||||
- **setup** — logs in as `qa-e2e` and `qa-e2e-admin` (fleet-managed IdP test
|
||||
users; the admin is a `homepage-admins` member), writes
|
||||
`.auth/qa-e2e{,-admin}.json` storage states.
|
||||
- **standard** — 10/12/13 with the user state.
|
||||
- **standard** — 10/12/13/16/17/18 with the user state
|
||||
(`tests/e2e/playwright.config.ts:33`).
|
||||
- **admin** — 11 with the admin state.
|
||||
- **guest** — 14/15 with an empty state.
|
||||
- **frankbook** — 19 with the admin state. **Excluded from every default run**: the
|
||||
@@ -64,7 +69,9 @@ cd tests/e2e && npx playwright test # ALL projects, frankbook included
|
||||
|
||||
Requires LAN reachability of `www.franksdank.cloud` (Pi-hole DNS or public).
|
||||
The suite is **not** part of `./tests/run.sh` — it needs the live fleet and
|
||||
real IdP credentials.
|
||||
real IdP credentials. It **is** a deploy gate: `scripts/deploy.sh` runs it and
|
||||
aborts with `DEPLOY INCOMPLETE: e2e gate FAILED` when it does not pass
|
||||
(`scripts/deploy.sh:278-285`).
|
||||
|
||||
## Gotchas (all paid for live)
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: "One Caddy fronts both hosts."
|
||||
tags:
|
||||
- architecture
|
||||
- network
|
||||
timestamp: 2026-09-02
|
||||
timestamp: 2026-10-18
|
||||
---
|
||||
|
||||
# Network Architecture
|
||||
@@ -40,7 +40,7 @@ graph TB
|
||||
POST --> PROM[Prometheus :9090]
|
||||
DIRECT -->|3000 + ssh 2222| GITEA[Gitea]
|
||||
DIRECT -->|3005| OWEBUI[OpenWebUI]
|
||||
DIRECT -->|3002| GRAFANA[Grafana :3000]
|
||||
POST -->|authenticated| GRAFANA[Grafana :3000]
|
||||
DIRECT -->|8083 web UI| PIHOLE[Pi-hole]
|
||||
AUTH -->|login UI + sessions| AUTHDB[(Authentik Postgres :5432)]
|
||||
SEARCH -.->|tunnel exit| GLU[Gluetun VPN]
|
||||
@@ -53,21 +53,31 @@ graph TB
|
||||
CAL[Calibre-Web :8083]
|
||||
PLEX[Plex :32400]
|
||||
JEL[Jellyfin :8096]
|
||||
ARR[*arr stack + qBittorrent]
|
||||
end
|
||||
|
||||
POST -->|romm| ROMM
|
||||
subgraph FRANKBOOK["FrankBook-Pro 192.168.0.112"]
|
||||
ARR[*arr stack + qBittorrent]
|
||||
end
|
||||
POST -->|files| COPY
|
||||
DIRECT -->|plex plain-HTTP passthrough| PLEX
|
||||
DIRECT --> CAL
|
||||
DIRECT --> JEL
|
||||
DIRECT --> ARR
|
||||
DIRECT -->|own auth, no Anubis| ARR
|
||||
```
|
||||
|
||||
Guarded (through Anubis): homepage, search, prometheus, romm, files.
|
||||
Exempt by construction: `auth.` (the IdP login itself), plex (plain HTTP),
|
||||
gitea (git smart-HTTP clients cannot solve JS challenges — `/info/refs` and
|
||||
`git-*-pack` pass unchallenged), grafana (own auth).
|
||||
Guarded (Anubis `:8923` → Caddy `:8016` → Authentik outpost → Caddy `:8017`):
|
||||
homepage (`www.`), search, **grafana** (`dankclaw/Caddyfile:128-129`),
|
||||
prometheus (`:135-137`), loki (`:141-143`), seerr (`:148-150`), marreta
|
||||
(`:155-160`), romm (`:167-169`), files (`:172-174`). Exempt / own-auth: `auth.`
|
||||
(the IdP login itself), `ai.` (OpenWebUI, its own OIDC), gitea (git smart-HTTP
|
||||
clients cannot solve JS challenges — `/info/refs` and `git-*-pack` pass
|
||||
unchallenged), pihole (Caddy `basicauth`, `:167`), plex (plain HTTP),
|
||||
books/jellyfrank (own logins), `hermes.`/`hermesadmin.`, and the *arr vhosts
|
||||
that terminate on FrankBook-Pro (`:254-281`, "exempt by construction: own
|
||||
auth"). Grafana is **not** exempt even though it signs in through authentik as
|
||||
an OAuth2 relying party (`:123`) — the chain wraps it too. `sonarr.` has no
|
||||
vhost at all (LAN `192.168.0.112:8989` only, `:265-267`).
|
||||
|
||||
Dankserver runs no proxy of its own. Its services expose published LAN ports, and the Dankclaw Caddy routes the names to those ports.
|
||||
|
||||
@@ -78,20 +88,31 @@ gitea (git smart-HTTP clients cannot solve JS challenges — `/info/refs` and
|
||||
| LAN | `romm.franksdank.cloud` → 192.168.0.143 | Pi-hole (`addn-hosts`) |
|
||||
| WAN | `romm.franksdank.cloud` → 71.227.227.172 | Porkbun A record |
|
||||
|
||||
Users type a name and nothing else. Caddy maps the name to the upstream. The split between the two resolvers removes the need for router NAT loopback. See [[LAN-DNS]] for the flow and the router hand-off.
|
||||
Users type a name and nothing else. Caddy maps the name to the upstream. The
|
||||
split between the two resolvers removes the need for router NAT loopback.
|
||||
Verified 2026-10-18: `dig +short @192.168.0.143 romm.franksdank.cloud` →
|
||||
192.168.0.143, and a public resolver returns 71.227.227.172 for the same name.
|
||||
See [[LAN-DNS]] for the flow and the router hand-off.
|
||||
|
||||
## TLS
|
||||
|
||||
Caddy holds one Let's Encrypt certificate per vhost, issued and renewed through the DNS-01 challenge via the Porkbun module. No inbound port 80/443 is required. Details in [[Caddy]].
|
||||
|
||||
## Gluetun Path (SearXNG only)
|
||||
## Gluetun Path (SearXNG + Marreta)
|
||||
|
||||
`gluetun.container`, `searxng.container` and `searxng-valkey.container` all set
|
||||
`Network=searxng.network` in their Quadlet sources (runtime network
|
||||
`systemd-searxng`); only those three share the tunnel. The old compose idiom
|
||||
(`network_mode: service:gluetun`) is gone — a shared named network is what
|
||||
carries SearXNG's outbound traffic through the VPN exit. Everything else on
|
||||
Dankclaw uses the normal LAN route. This matches KB Pattern 2 in [[Gluetun]].
|
||||
`gluetun.container` and `searxng-valkey.container` set
|
||||
`Network=searxng.network` (runtime network `systemd-searxng`), while
|
||||
`searxng.container`, `marreta.container` and `marreta-browser.container` join
|
||||
the tunnel the modern way — `Network=gluetun.container`
|
||||
(`dankclaw/searxng/quadlet/searxng.container:18`,
|
||||
`dankclaw/marreta/quadlet/marreta.container:34`,
|
||||
`dankclaw/marreta/quadlet/marreta-browser.container:25`), the Quadlet
|
||||
equivalent of the retired compose `network_mode: service:gluetun`. **Five**
|
||||
containers share the VPN exit, not three, and Marreta's outbound fetches leave
|
||||
through the same WireGuard tunnel as SearXNG's. Pi-hole is a different kind of
|
||||
exception (`Network=slirp4netns`, `dankclaw/pihole/quadlet/pihole.container`);
|
||||
everything else on Dankclaw uses the normal LAN route. This matches KB Pattern
|
||||
2 in [[Gluetun]].
|
||||
See [[Container Network Namespaces]] for which addresses are reachable from that
|
||||
namespace (none of the unpublished host-netns listeners).
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: "This repository tests its configuration at defined seams."
|
||||
tags:
|
||||
- architecture
|
||||
- testing
|
||||
timestamp: 2026-09-01
|
||||
timestamp: 2026-10-18
|
||||
---
|
||||
|
||||
# Testing Policy
|
||||
@@ -16,13 +16,14 @@ This repository tests its configuration at defined seams. The tests run with `ba
|
||||
| Seam | File | What it asserts |
|
||||
|------|------|-----------------|
|
||||
| Compose validity | `tests/compose_validity.bats` | YAML parses, services have images, no named volumes |
|
||||
| Env consistency | `tests/env_consistency.bats` | every `${VAR}` is defined in `.env.example`; no real secrets; the live gitea password never appears |
|
||||
| Caddyfile validity | `tests/caddyfile.bats` | per-host Caddyfile, `.local` convention, balanced braces, basic auth present |
|
||||
| Docs completeness | `tests/docs_completeness.bats` | every compose service has a docs page; index links every page |
|
||||
| Env consistency | `tests/env_consistency.bats` | every compose file has a **sibling** `.env.example` (`:9`) in which every `${VAR}` is defined (`:17`); placeholders only (`:31`); the live gitea database password never appears (`:37`) |
|
||||
| Caddyfile validity | `tests/caddyfile.bats` | the Caddyfile lives on **dankclaw only** (`:15`, not per-host), flat `franksdank.cloud` names with no `.local` leftovers (`:20,:24`), balanced braces, `caddy validate` when the binary exists, the renderable homepage basicauth placeholder, the quadlet/Porkbun/loki/prometheus guardrails |
|
||||
| Docs completeness | `tests/docs_completeness.bats` | every compose service has a docs page; `index.md` links every page; **no wikilink in the vault points at a page that does not exist** (`:37`) |
|
||||
| Script syntax | `tests/scripts_syntax.bats` | `bash -n` clean, executable bits, shellcheck when available |
|
||||
| Deployment flow | `tests/deployment_flow.bats`, `tests/deployment_scoping.bats` | scoped dispatcher exists, targets are known, service plans isolate inference, Caddy ownership is guarded, and SSH reachability is checked (skips offline) |
|
||||
| Quadlet units | `tests/*quadlet*.bats` | every unit is boot-persistent, self-healing, repo-provenanced, secret-free |
|
||||
| E2E (browser) | `tests/e2e/` + `tests/e2e_scaffold.bats` | Playwright drives the live guard chain; the bats seam asserts structure and credential hygiene. See [[E2E Suite]] |
|
||||
| Per-service / unit seams | `tests/llm_units.bats`, `tests/frank_{archon,dragoon,zealot}_unit.bats`, `tests/llm_secrets.bats`, `tests/homepage_{caddy,checker,config,deploy,pages}.bats`, `tests/{anubis,authentik,hermes_webui,pihole,mount_entropy,searxng_limiter,autoresearch_measure,changed_tests}.bats`, `tests/{caddy,dankserver,frankbook,marreta,observability,open_webui,searxng}_quadlet.bats`, `tests/comfyui_rocm.bats` | the ~30 named seams the summary rows above do not list: LLM systemd-unit shape and env hygiene, homepage config/pages/deploy behaviour, and one detail-seam per deployed service |
|
||||
|
||||
## Focused pre-commit testing
|
||||
|
||||
|
||||
Reference in New Issue
Block a user