The image is published to GHCR as the release's version when a release dispatches docker.yml, and never as latest or per commit. Pushes and pull requests that touch it build it and try headless (with and without a token) and browser mode, without publishing. The image: node:24-slim pinned by digest (the major CI tests on), npm ci from the lockfile in its own layer, only src, site, scripts and the harness copied in (an allow-list .dockerignore), root-owned and run as node, /saves ready for --save-dir. The entrypoint runs the servers with node directly and, with no SOT_MCP_TOKEN, makes a token for the run and prints it (MCP_NO_TOKEN=1 to opt out); the docs publish ports to 127.0.0.1 and explain --allow-host. Labels, SBOM and provenance on push. Every GitHub Action in every workflow is pinned to a commit SHA with its version, and Dependabot keeps the actions, the image's base and the npm tools current. tests/docker.test.js guards all of it. The ADR and the github-pages skill say the image is a tool: GHCR only, never Pages.
70 lines
4.8 KiB
Markdown
70 lines
4.8 KiB
Markdown
---
|
|
name: github-pages
|
|
description: Series of Tubes is hosted on GitHub Pages and nowhere else, non-negotiably. Use before any change to hosting, deploys, the build output, caching, the service worker, new runtime requests or anything that would need a server, and whenever someone suggests another host.
|
|
---
|
|
|
|
# GitHub Pages, always
|
|
|
|
Series of Tubes is served by GitHub Pages at https://seriesoftub.es and **only** there. This is settled
|
|
([docs/adr/0001-github-pages-only.md](../../../docs/adr/0001-github-pages-only.md)) and not up for
|
|
discussion: do not propose, prepare or "keep the door open" for another host, a CDN in front, a
|
|
backend or server-side rendering, even when asked to evaluate options. If a feature seems to need
|
|
one, redesign the feature.
|
|
|
|
## What that means for a change
|
|
|
|
- **The output is static files.** `npm run build` writes `_site/`: the assembled page, `site/`'s files,
|
|
`version.json`. No server code, no runtime secrets: everything there is public.
|
|
- **No HTTP headers, redirects or rewrites.** Pages ignores `_headers`, `_redirects`, `.htaccess`,
|
|
`vercel.json`, `netlify.toml`. Need a policy? Use a `<meta>` tag. Need a different URL? Add a
|
|
static file there.
|
|
- **Caching is Pages' (short, the same for every file) plus the service worker's.** Offline play and
|
|
updates are `site/sw.js`'s job; its cache name carries the version. When you add a file the game
|
|
needs offline, add it to `CORE` there.
|
|
- **Same origin.** The page, dictionaries, icons and data come from seriesoftub.es. Do not add CDN
|
|
libraries or third-party APIs the game needs to work; the web fonts and the analytics counter are
|
|
the only exceptions and the game runs without them.
|
|
- **More files are fine, from the same origin.** Pages serves many small files well over HTTP/2.
|
|
Still: the game page itself stays one assembled `index.html` (see
|
|
[ADR 0002](../../../docs/adr/0002-one-page-assembled-at-build.md)), and anything the first frame
|
|
needs must not add a round trip.
|
|
- **Limits:** about 1 GB for the whole site, 100 MB per file.
|
|
- **Paths:** the site lives at the domain root (`site/CNAME`), so `/` paths are fine; unknown paths get
|
|
`404.html`.
|
|
- **Local tools are not hosting.** `npm run dev` and the MCP server (`npm run mcp`, also over `--http`)
|
|
run on a developer's own machine against a checkout; nothing they serve is deployed, and the game
|
|
never depends on them. Their code stays out of `_site/` (`src/agent/` is development-only, see
|
|
`docs/adr/0004-dev-only-code.md`).
|
|
- **The container image is a tool too.** `docker/` packages those tools; `docker.yml` publishes it to GHCR for releases
|
|
(version tags only, no `latest`) and never to Pages. Someone may run its development server where they like; that is
|
|
not a host of the game, and the game never depends on it.
|
|
|
|
## How it deploys
|
|
|
|
Only releases deploy. Bumping `version` in `package.json` on `main` runs `auto-release.yml`, which tags,
|
|
publishes the GitHub release and starts `release.yml`: test, `REQUIRE_NOTES=1 npm run build`,
|
|
`actions/upload-pages-artifact` with `./_site`, `actions/deploy-pages`. That job is the only one with
|
|
`pages: write`. Pushes to `main` and pull requests build but never deploy. The `release` skill has the
|
|
steps.
|
|
|
|
**The one exception: the weekly puzzle.** Every Sunday at 03:37 UTC `weekly-puzzle.yml` commits the new
|
|
`site/puzzles/weekly/<key>.json` to `main` (data only, no version bump) and starts `release.yml` for the **live
|
|
release tag** with `weekly=true`. That run rebuilds exactly the live release, with every weekly file from `main`
|
|
added, checks them with `scripts/weekly-puzzle.js --check`, and deploys it in the same `pages` concurrency group.
|
|
Players get no update banner (the version does not change). Every release build also copies all weekly files from
|
|
`main`, so a release never drops a published week, and regenerates (in the build, deterministically) any week
|
|
not over yet that the release's prices no longer fit. Weekly files are plain JSON the game fetches only when the
|
|
Puzzles list opens and never trusts; the service worker serves them network-first. The weekly scenario rides along in
|
|
the same run: `scripts/weekly-scenario.js` writes `site/scenarios/weekly/<key>.json` (fetched when the Scenarios list
|
|
opens), committed and deployed with the puzzle, never by a second workflow. See `docs/ARCHITECTURE.md`.
|
|
|
|
## Before you hand back a change that touches the build, deploy or loading
|
|
|
|
```bash
|
|
npm run build && npm run serve # the production build, served as static files
|
|
npm test -- tests/pages.test.js # static-only, all references resolve, Pages-only deploy
|
|
```
|
|
|
|
`tests/pages.test.js` fails on host configuration files, files over the limits, local references
|
|
that do not exist in `_site/`, scripts loaded from other origins, and any workflow that deploys
|
|
anywhere else. Do not weaken it to make a change pass; change the change.
|