portal/deploy/README.md

# Deploy: CTAO portal demo on strapi-experimental.cyfronet

Everything runs rootless as user `strapi`. Footprint on the machine:
ONE directory (`~/ctao-portal-demo/`) + 4 unit files in `~/.config/`.
Uninstall restores the machine exactly (see bottom). No secrets in any file.

Two Gitea repos by design: `ctao/portal` (code, developed by the team) and
`ctao/content` (Markdown + uploads, committed by the CMS). The build overlays
content onto code; a push to EITHER republishes the site.

```
~/ctao-portal-demo/
├── gitea-data/    # Gitea state (repos, SQLite, accounts)  ← the ONLY thing worth backing up
├── gitea-config/  # Gitea app.ini (generated from env)
├── repo/          # clone of the code repo (created by first build)
├── content/       # clone of the content repo (created by first build)
├── releases/      # <code>-<content>/ dirs + `current` symlink (what nginx serves)
├── state/         # last-built release id
├── npm-cache/     # npm cache for the build container (created by build.sh)
├── bin/build.sh   # copied from deploy/ (source of truth stays in the code repo)
└── config/nginx.conf
```

Host prerequisites: `podman`, `curl`, `jq` (build.sh checks and says which is
missing). Everything else runs inside containers.

| Port | What | Exposed as |
|---|---|---|
| 3000 | Gitea | https://astro-git.isl-dev.grid.cyfronet.pl (ingress vhost) |
| 8080 | portal (nginx, static) | https://astro.isl-dev.grid.cyfronet.pl (ingress vhost) |

## Publish the simplified portal from `main`

1. Check that `ctao/content:main` contains the four Example files in `pages/`
   (listed in `src/data/examples.json`) and the uploads they reference. They
   are already committed there (`a3452d7`, "demo lorem ipsum pages"). News and
   other page files can remain in the content repository; this portal loads
   only the four Example files.
2. Push the content branch to Gitea as `ctao/content:main`, and the code
   branch as `ctao/portal:main`. These are separate pushes; Bitbucket is
   not the deployment remote.
3. Copy the updated `build.sh` to `~/ctao-portal-demo/bin/build.sh` and the
   updated `ctao-portal-build.service` to `~/.config/systemd/user/`. Reload
   systemd with `systemctl --user daemon-reload`. The service explicitly sets
   `CODE_BRANCH=main` and `CONTENT_BRANCH=main`; the script defaults agree.
4. Start the build service or let its timer run. It overlays `pages/` and
   `uploads/`, clears the previous news overlay, and runs `npm run check`
   before the atomic release switch. Missing Example pages fail the build.
5. Verify the four `/example/…/` pages and empty `/news/`. Sign in at `/admin/`,
   save an Example title, and check that a commit appears on
   `ctao/content:main` and the rebuilt page reflects it.

The OAuth client and public portal origin stay the same. Sveltia's
`backend.branch` in `public/admin/config.yml` must always match
`CONTENT_BRANCH`. Branches are selected independently; a single `BRANCH`
environment variable is no longer used. For a separate preview hostname,
update the site origin, OAuth redirect, and Gitea CORS together.

To undo the simplification in shared code history, use
`git revert -m 1 <simplification-merge-commit>` on `main` and publish the
resulting commit. The previous portal code is also preserved at `0772462`.
For an immediate deployment rollback, restore the previous release and worker
script/service configuration. Content has its own history: reverting a code
commit does not revert CMS edits. Keep the old content files available if
the previous portal may be restored.

## Install (each step reviewed before running; [W] = writes to the machine)

1. **[W]** `loginctl enable-linger $USER`. Without lingering every user unit
   dies at logout and nothing starts after a reboot. Verify:
   `loginctl show-user $USER -p Linger` → `Linger=yes`.
2. **[W]** `mkdir -p ~/ctao-portal-demo/{gitea-data,gitea-config,releases,state,bin,config} ~/.config/containers/systemd ~/.config/systemd/user`
3. **[W]** Copy files from this dir (scp):
   - `ctao-demo-gitea.container`, `ctao-demo-web.container` → `~/.config/containers/systemd/`
   - `ctao-portal-build.service`, `ctao-portal-build.timer` → `~/.config/systemd/user/`
   - `build.sh` → `~/ctao-portal-demo/bin/` (`chmod +x`)
   - `nginx.conf` → `~/ctao-portal-demo/config/`
   - `Containerfile.build` → anywhere (needed once, for the next step)
4. **[W]** Pull the images at the digests pinned in the unit files (one-time,
   needs internet) and build the build image:
   `podman pull docker.io/gitea/gitea@sha256:<digest from ctao-demo-gitea.container>`
   `podman pull docker.io/library/nginx@sha256:<digest from ctao-demo-web.container>`
   `podman build -t localhost/ctao-portal-build:1 -f Containerfile.build .`
   (Upgrading later = pick new digests deliberately, update the pins in the
   `.container` files / `Containerfile.build`, re-pull, re-build.)
5. **[W]** `systemctl --user daemon-reload && systemctl --user start ctao-demo-gitea`
6. **[W]** Create the Gitea admin. Run it interactively in a terminal so the
   password never lands in a file or shell history:
   `podman exec -it ctao-demo-gitea gitea admin user create --admin --username <you> --email <you@…> --random-password`
7. **[W]** In the Gitea UI: create org `ctao` with repos `portal` and
   `content` (both public read). The content `main` branch needs the four
   Example pages described above. Then, from your workstation, push both over
   the vhost with a repo-scoped token:
   `git push https://<user>:<token>@astro-git.isl-dev.grid.cyfronet.pl/ctao/portal.git main`
   `git push https://<user>:<token>@astro-git.isl-dev.grid.cyfronet.pl/ctao/content.git main`
8. **[W]** `systemctl --user enable --now ctao-portal-build.timer`. The first run
   clones + `npm ci` + builds (minutes); later runs are seconds. Wait until
   `journalctl --user -u ctao-portal-build -n 5` shows `published <sha>`
   (starting nginx earlier just serves 404s until the first build lands).
9. **[W]** `systemctl --user start ctao-demo-web`
10. **[R]** Verify: `curl -s -o /dev/null -w '%{http_code}' http://localhost:8080/`
   and `journalctl --user -u ctao-portal-build -n 20` (shows measured build times).

Editor accounts need WRITE access to `ctao/content` (Gitea → repo →
Collaborators, or a team); public read alone lets them sign in but every
save fails.

## CMS sign-in (Sveltia ↔ Gitea OAuth)

- Gitea OAuth2 app (PKCE, `confidential_client=false`, no secret) with
  redirect `https://astro.isl-dev.grid.cyfronet.pl/admin/`; its client id is
  the `app_id` in `public/admin/config.yml`.
- CORS is pinned in `ctao-demo-gitea.container`: `ALLOW_DOMAIN` takes the
  FULL portal origin with scheme (a bare hostname silently disables CORS in
  Gitea 1.27; there is no `SCHEME` key) and `HEADERS` must include
  `Authorization` or authenticated API calls from the browser fail.
- OAuth requires a secure context: the vhosts must stay HTTPS.
- Changing origins later = edit the quadlet env + the OAuth app's redirect
  URI + `config.yml`, then `systemctl --user daemon-reload && systemctl --user restart ctao-demo-gitea`.

## Uninstall (leaves only podman's own storage metadata)

```
systemctl --user disable --now ctao-portal-build.timer
systemctl --user stop ctao-demo-web ctao-demo-gitea
rm ~/.config/containers/systemd/ctao-demo-*.container \
   ~/.config/systemd/user/ctao-portal-build.{service,timer}
systemctl --user daemon-reload
podman rmi localhost/ctao-portal-build:1 docker.io/gitea/gitea:1.27-rootless \
  docker.io/library/nginx:stable-alpine docker.io/library/node:24-alpine
rm -rf ~/ctao-portal-demo
loginctl disable-linger $USER   # only if nothing else of yours should survive logout
```

## Notes

- A release that fails to build is not retried until either repo gets a new
  commit (`state/last-failed` guards against a 10 s rebuild loop). To force a
  retry of the SAME release (e.g. after fixing `bin/build.sh` itself):
  `rm ~/ctao-portal-demo/state/last-failed`.

- **Only pushes to the machine's Gitea auto-deploy** (code and content repos
  alike). Changes to `deploy/*` need a manual
  re-copy: `build.sh` → `bin/`, `nginx.conf` → `config/` +
  `systemctl --user restart ctao-demo-web`, unit files →
  `~/.config/…` + `systemctl --user daemon-reload` (+ restart). This is
  deliberate: the build pipeline must not execute host-side code straight
  from the content repo.
- Publish latency = poll (≤10 s) + build (measured: astro build 5–7 s on the
  2 vCPU VM, whole build.sh 16–21 s; every build's time lands in the journal).
- Internet needed only for: image pulls (install) and `npm ci` when the
  lockfile changes. Routine rebuilds are fully offline.
- Memory caps (`MemoryHigh`) keep us polite next to Outline + Strapi;
  the build container is capped at 1 GB via `podman run --memory`. Watch the
  first `npm ci` + build in the journal; if it OOMs inside its cgroup
  (contained, just retries), raise the cap.
- Build isolation: build containers join the Gitea container's network
  namespace (`--network=container:ctao-demo-gitea`): repo/npm code sees
  Gitea on localhost:3000 but cannot reach host loopback services. (Rootless
  netavark bridges don't work here: no `ip_tables` kernel module, no sudo.)
- Secrets inventory: Gitea admin password (typed interactively, lives only
  in Gitea's DB) and repo-scoped push tokens (managed in Gitea); that's the
  complete list. Build/poll/serve use none.