| @@ -0,0 +1,67 @@ |
| 1 | +# Deployment |
| 2 | + |
| 3 | +The site runs on [Render](https://render.com) as a container image. Every push to `main` that changes |
| 4 | +more than documentation runs `.toboggan/workflows/deploy.yml`: |
| 5 | + |
| 6 | +``` |
| 7 | +check ── image ── deploy |
| 8 | +``` |
| 9 | + |
| 10 | +1. **check** (instance runner): `bun run check`, `bun run test`, `bun run build`. |
| 11 | +2. **image** (`starfleet-podman` runner): `scripts/publish-image.sh <short commit> --push` builds |
| 12 | + `deploy/Containerfile` and smoke-tests the image. The test checks that it boots, that `/healthz` |
| 13 | + answers with its version, and that `/login` renders. It then pushes |
| 14 | + `toboggan.cloud/starfleet/starfleet-ui:<commit>` and `:latest` with the job's own token. |
| 15 | +3. **deploy** (instance runner, `production` environment): calls Render's deploy hook with |
| 16 | + `imgURL=` set to that exact image. It then polls `$RENDER_URL/healthz` until the site reports the |
| 17 | + commit (15 minutes at most). |
| 18 | + |
| 19 | +A manual run on `main` (`tob workflow run deploy.yml`) redeploys. |
| 20 | + |
| 21 | +## Why it works this way |
| 22 | + |
| 23 | +- **Render pulls a public image.** Render's registry credentials cover GitHub, GitLab, Docker Hub, |
| 24 | + Google Artifact Registry and AWS ECR, not toboggan. So the repository is public, and the package |
| 25 | + a workflow pushes inherits that. The image holds no secrets: each player's API key lives in their |
| 26 | + own cookie. |
| 27 | +- **A podman runner of our own.** toboggan.cloud's podman runner serves the toboggan repository only, |
| 28 | + and `corellia-starfleet-podman` is scoped to starfleet-api. |
| 29 | +- **The deploy hook is a secret.** Its URL carries a key. It lives in the `production` environment, |
| 30 | + which only runs on the default branch can read. It never appears on a command line or in the log. |
| 31 | + |
| 32 | +## One-time setup |
| 33 | + |
| 34 | +1. **A runner for this repository.** Run `tob runner token -R starfleet/starfleet-ui` to get a |
| 35 | + registration token. On the CI host, register it with the label `starfleet-podman`, the same way |
| 36 | + starfleet-api's runner is set up (toboggan `docs/registry.md`, "Building in CI"). Alternatively, |
| 37 | + register one runner for the whole `starfleet` igloo on `/runners` so both repositories share it. |
| 38 | +2. **The first image.** Push `main`. With no `RENDER_URL` set yet, the run publishes the image and |
| 39 | + skips the deploy job. |
| 40 | +3. **The Render service.** Create a Web Service from the existing image |
| 41 | + `toboggan.cloud/starfleet/starfleet-ui:latest` with no credential, and set its health check path |
| 42 | + to `/healthz`. No environment variables are needed, because Render sets `PORT`. Optionally set |
| 43 | + `STARFLEET_API_URL` to point at another game server. |
| 44 | +4. **The hook and the address:** |
| 45 | + - `tob secret set RENDER_DEPLOY_HOOK --env production`, pasting the service's deploy hook |
| 46 | + (Settings → Deploy Hook). |
| 47 | + - `tob variable set RENDER_URL https://<service>.onrender.com`. |
| 48 | +5. **Deploy.** Run `tob workflow run deploy.yml`, or push. |
| 49 | + |
| 50 | +## Running the image locally |
| 51 | + |
| 52 | +```sh |
| 53 | +scripts/publish-image.sh local # build + smoke test, no push |
| 54 | +podman run --rm -p 3000:3000 toboggan.cloud/starfleet/starfleet-ui:local |
| 55 | +``` |
| 56 | + |
| 57 | +## Configuration |
| 58 | + |
| 59 | +| Variable | Default | | |
| 60 | +|---|---|---| |
| 61 | +| `STARFLEET_API_URL` | `https://starfleet.glo.quebec` | game API the server proxies to | |
| 62 | +| `PORT` / `HOST` | `3000` / `0.0.0.0` (image) | Render sets `PORT` | |
| 63 | +| `STARFLEET_UI_VERSION` | `dev` | stamped by `publish-image.sh`; `/healthz` answers it | |
| 64 | +| `CONNECTION_IDLE_TIMEOUT` | `60` | seconds; must exceed the API's 15 s SSE keepalive | |
| 65 | + |
| 66 | +Variables are declared in `src/env.ts`. SvelteKit 3 inlines any variable that isn't declared there |
| 67 | +at build time. |