Operations

Portal does not deploy itself. It publishes versions; each site decides when to take one.

Cut a release

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, iris, hash.txt, site/) to the Gitea release. Plain pushes to main only run the tests: nothing reaches production from this repo.

The same job re-pins, tests and tags iris to match, so a portal change to anything the lint reads fails the release rather than the next content push.

Before cutting, move the Unreleased lines in CHANGELOG.md under a heading for the new version. That section becomes the release notes, and the table at the end of the file records which version each site runs.

Pkg files are content-hashed (hash-files = true, instances run with LEPTOS_HASH_FILES=true), so a freshly served page can never pair a stale cached bundle with new wasm.

Roll it out

In the content repo, one line of .gitea/workflows/deploy.yml:

env:
  PORTAL_RELEASE: v0.4.0

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 and secrets, restarts app@<instance> and refreshes the Caddy route. Every rollout is a commit, so reverting a bad version is git revert and a push.

Sites upgrade independently and may pin different versions.

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

Add a site

A new content repo with a copy of an existing deploy.yml (change INSTANCE, the port and the 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 handles all branding; no portal change is needed.

Environment

Runtime configuration is environment variables; src/main.rs is the authority and each content repo’s deploy.yml holds the production values.

Mail is delivered by gdo, a separate unit on the same host reading the same NATS.

Rate limiting

Every request passes a per-caller-IP limit before a session is loaded or a handler is entered: a burst of 30, refilled one every two seconds. A visitor filling in a form never reaches it (a page load fetches several resources at once); a script does.

Either set to 0 turns it off, for an instance behind something that already does this. The caller is read from X-Forwarded-For or X-Real-IP, falling back to the socket — all of these instances are behind Caddy.

This is a fence, not an accounting system. What keeps uploads honest is the policy check on the route itself.

Attachments

A type: file field stores an object key in the record. The file comes back out at:

GET /attachment/{bucket}/{record}/{field}

which reads the key out of that record rather than taking one from the caller, so a file can only be fetched through a record somebody is allowed to see, and a leaked key is a link to nothing. Reading it needs the same policy permission as reading the bucket on a desk.

Uploads need a bucket and a key in the Garage on the host:

garage bucket create <site>-attachments
garage key create <site>-portal-uploads
garage bucket allow --read --write <site>-attachments --key <site>-portal-uploads

then GARAGE_S3_ENDPOINT, GARAGE_ACCESS_KEY, GARAGE_SECRET_KEY and GARAGE_UPLOADS_BUCKET in that instance’s env. Unset, an upload field fails closed rather than appearing to work and storing nowhere.

The report

GET /report is public and answers with counts only: per bucket, per storyline, per state. It is what the trainer reads to compare the storylines on what people did.

The docs site

These pages are portal.uhhm.no: docs/ built with mdBook (book.toml, docs/SUMMARY.md) by .gitea/workflows/docs.yml on every push to main that touches them, and put to git-pages the way every static site on uhhm.no is (uhhm/infrastructure PAGES.md). The changelog is the book’s last page. mdbook serve previews it locally.

Who deploys what

Both hosts deploy from CI now, and a rollout is the same commit either way: bump PORTAL_RELEASE in the site’s own content repo.

The kasse grant is a single sudoers line (/etc/sudoers.d/30-portal-deploy). It exists so a workflow can pick which of three known instances gets which published portal tag, and nothing else.

Both paths health-check the instance afterwards without a forwarded header. A check that sends the header Caddy would send cannot tell you the site is broken for everything that is not Caddy, which is how v0.5.1 reached a host.

IRIS_RELEASE in a repo’s lint workflow should equal its PORTAL_RELEASE. Bump it only once iris’s own publish job has attached the binary for that tag - portal’s release tags iris, but iris builds and uploads on its own run, and a pin bumped in between fails the lint on a download that is not there yet.