Bendik Aagaard LynghaugandClaude Opus 5
214d4eb85c
A MemoryStore meant every restart signed out every desk on the site being deployed. Bearable while a desk is three people, and not the kind of thing that gets better on its own. They live in NATS KV now: the JetStream already under the events, the projections, the content reload and the access questions. No new service, no new store, and the same bucket a second instance of a site would read if there ever is one. `create` draws a fresh id rather than writing over a session already at that key, the bucket's `max_age` collects what nobody comes back for, and a record's own expiry is what answers a load, whatever the bucket still holds. Proved the only way it can be: a store opened twice against one JetStream, which is what two runs of the binary are. Also fixed, while there: the integration test asserted a record's projected state was one that `aggregates::transition` never writes - it appends events, the desk handler updates the projection - so it failed whenever it was actually run. It now asserts what it says it does, that a mailed reply leaves the state alone. test.yml has been red since 0.3.47 while publish.yml stayed green, which is how v0.4.0 went out over it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
4.6 KiB
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.
NATS_URL |
events, projections, sessions, content reload, access questions |
CONTENT_REPO, CONTENT_BRANCH |
the repo that is the site |
KANIDM_URL, OAUTH2_CLIENT_ID, OAUTH2_CLIENT_SECRET |
sign-in |
KANIDM_API_TOKEN |
invites and grants:; unset, neither happens |
PUBLIC_URL, SITE_NAME |
what the site calls itself in links and mail |
GITEA_API_TOKEN |
authenticated resource pulls |
AUTOMATION_READ_TOKEN |
the automation KV read endpoint |
GARAGE_* |
uploads |
MAPBOX_TOKEN |
map tiles, proxied; unset, maps are off |
GARAGE_* (4) |
attachments; see below. Unset, upload fields fail closed |
PORTAL_RATE_BURST, PORTAL_RATE_SECONDS |
the rate limit; see below |
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.
PORTAL_RATE_BURST |
how many requests at once, default 30 |
PORTAL_RATE_SECONDS |
seconds per refilled request, default 2 |
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.