portal/README.md

portal

The question runtime behind uhhm.no. Every page, form, review desk, and state machine it serves is declared in the questions content repo — this codebase is the engine that renders, enforces, and records, and it special-cases none of it.

What the engine provides

• Content-driven pages (src/content.rs, src/app.rs): YAML loaded from Gitea at boot and hot-swapped on a NATS reload signal; a bad push keeps the last-good content serving. A page's id is its URL; qualifies gates it to a Kanidm group.
• State machines as content (src/aggregates/): aggregates.yaml declares each bucket's states and legal transitions; the engine replays a record's event history and refuses undeclared moves, with optimistic concurrency (CAS on the event log's sequence) against racing decisions. An empty history reseeds from the KV projection, so wiping the event stream strands nothing.
• Durable events + projections (src/events/, src/answers.rs): every submission and decision appends to a JetStream event log and projects into a NATS KV bucket pages read back; every one also publishes on portal.answers.submitted for automations (n8n) to react to.
• Answer chains (src/chain.rs): each submission hashes its parent(s), so a visitor's path through the questions is a verifiable lineage; ?chain= links carry it, and self-service transitions (unsubscribe) authorize by holding one.
• Live resources (src/resource.rs): content can pull a KV bucket, Gitea starred/org repos, or any public JSON URL (SSRF fail-closed), reshaped by a content-declared jq filter.
• Review desks: any Kv resource with transitions renders rows with per-state action buttons and one shared confirm per alternative — owners walk records through their graphs without bespoke UI per bucket.

Binaries

• portal — the server (Leptos SSR + hydrate, Axum underneath).
• question_lint — headless content validation, shipped inside every release artifact so each content repo's CI lints with the exact portal version its instance runs; also works offline: question_lint --path <dir>.

Development

cargo leptos build            # full app (server + wasm)
cargo test --features ssr     # engine tests
cargo build --features ssr --bin question_lint

Runtime configuration is env vars (see src/main.rs, and each content repo's .gitea/workflows/deploy.yml for the values in production): NATS_URL, CONTENT_REPO/CONTENT_BRANCH, Kanidm OIDC (KANIDM_URL, OAUTH2_CLIENT_*), optional GARAGE_* for uploads, GITEA_API_TOKEN for authenticated resource pulls, AUTOMATION_READ_TOKEN for the automation KV read endpoint.

Release and deploy

Portal doesn't deploy itself — it publishes versions, and each site decides when to take one. The whole day-to-day surface is two commands:

Cut a release (here):

cargo release patch        # or minor / major

That bumps Cargo.toml, tags v<version>, and pushes; CI (.gitea/workflows/publish.yml) reacts to the tag, builds once, and attaches portal-v<version>.tar.gz (portal + question_lint + site/) to the Gitea release. Plain pushes to main only run the tests (test.yml) — nothing reaches production from this repo.

Roll it out (in a content repo): edit one line in that repo's .gitea/workflows/deploy.yml —

env:
  PORTAL_RELEASE: v0.1.1   # <- bump, commit, push

Its CI downloads the pinned artifact, ships /srv/app/<instance>/releases/<tag>, flips current, rewrites the instance env from that repo's own Actions variables/secrets, restarts app@<instance>, and refreshes the Caddy route. Every rollout is a commit, so reverting a bad version is git revert + push. Sites upgrade independently: uhhm.no (uhhm/questions → app@uhhm-portal, :3010) and redoal.com (redoal/questions → app@redoal-portal, :3020) can pin different versions.

Content changes never come through any of this — they hot-reload live from the content repos over NATS.

Add a site: new content repo with a copy of an existing deploy.yml (change INSTANCE, port, domains), Actions variables (KANIDM_URL, OAUTH2_CLIENT_ID, PUBLIC_URL, SITE_NAME) and secrets (NATS_URL, OAUTH2_CLIENT_SECRET, PORTAL_GITEA_API_TOKEN — Gitea reserves the GITEA_ prefix for secret names), a Kanidm OAuth2 client, and DNS. site.yaml in the content repo handles all branding; no portal changes needed.