# Operations

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

## Cut a release

```sh
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](https://project.uhhm.no/uhhm/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`:

```yaml
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 |

Mail is delivered by [gdo](https://project.uhhm.no/uhhm/gdo), a
separate unit on the same host reading the same NATS.