Bendik Aagaard LynghaugandClaude Opus 5
d5de25e8c6
Two halves of the same evening.
Uploads were one-way. A `type: file` field put an object in the bucket
and wrote its key into the record, and nothing ever read it back - a
desk showed `0aba5734-...-drawing.pdf` as a string with no link, so a
builder could receive drawings and never open one.
`GET /attachment/{bucket}/{record}/{field}` streams it. The key is not
the credential and is not taken from the caller: it is read out of the
record named, so a file is reachable only through a record somebody is
allowed to see, and a key that leaks off a desk is a link to nothing.
And there was no rate limiting anywhere. A burst of 30 per caller IP,
refilled one every two seconds, outside the session layer so anyone
over it is turned away before a handler is entered. Well above a
person filling in a form - a page load fetches several resources at
once - and well below being a nuisance. PORTAL_RATE_BURST and
PORTAL_RATE_SECONDS retune it; either 0 turns it off for an instance
behind something that already does this.
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, 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.