Container image: releases only, a token by default, lean layers; every action pinned

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.
This commit is contained in:
Frederic Jung 2026-11-05 20:14:03 +01:00
parent 9c8cda44c1
commit 98735eb769
No known key found for this signature in database
16 changed files with 367 additions and 110 deletions

View file

@ -79,36 +79,49 @@ claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp
### In a container
Every push to `main` and every release publishes a multi-arch (amd64/arm64) image at
`ghcr.io/fjaeckel/seriesoftubes`, built from the repo by the `docker.yml` workflow: `latest` and the commit SHA on
pushes, the release's version (pre-releases included) on releases. It packages the dev server and the MCP server;
`node scripts/mcp.js --help` options go after the image name, and `--http 0.0.0.0:7777` is the default (a container
bound to loopback would be unreachable; pass your own `--http` to override).
Every release publishes a multi-arch (amd64/arm64) image at `ghcr.io/fjaeckel/seriesoftubes:<version>`
(`docker.yml`, dispatched by the release; pre-releases too). There is no `latest` and no image per commit: pick a
version from the [releases](https://github.com/fjaeckel/seriesoftubes/releases). It holds the MCP server and the
development server, nothing else from the repository, and runs as `node`, not root. It is published to GHCR only; the
game itself is served from GitHub Pages and nowhere else.
`MCP_MODE=headless` runs just the MCP server with a game of its own; the default (`browser`) also serves the
development page so a browser tab can play it, as above.
- **`MCP_MODE=browser`** (the default) serves the development page on 8080, with the relay, and runs the MCP server on
7777 driving that tab. **`MCP_MODE=headless`** runs only the MCP server, with a game of its own.
- **Options** go after the image name, to `scripts/mcp.js` (`node scripts/mcp.js --help`). The MCP server listens on
`0.0.0.0:7777` inside the container, since loopback there is unreachable; pass your own `--http` to change it.
- **A token, always.** The Host check stops browsers, not other clients, so a published port without a token is open to
anyone who reaches it. Give one with `-e SOT_MCP_TOKEN=…` (or `--token-file`); without one the container makes a
token for this run and prints it, with the `claude mcp add` line to use it. `MCP_NO_TOKEN=1` turns that off.
- **Publish the ports to loopback** (`-p 127.0.0.1:7777:7777`), as below. A bare `-p 7777:7777` listens on every
interface of the host, and Docker's rules go around ufw and firewalld. To reach it from elsewhere, keep the token,
add `--allow-host NAME` for the name or address clients use (requests naming the host's address are refused
otherwise, since that is not an address inside the container), and put TLS in front.
- **The relay has no token** (as with `npm run dev -- --host`): in browser mode, anyone who reaches port 8080 can drive
a game whose player turned agent mode on. Publish it to loopback too.
```sh
docker run -d -p 7777:7777 -e MCP_MODE=headless ghcr.io/fjaeckel/seriesoftubes
claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp
V=2.10.1 # a release
# Options are passed to scripts/mcp.js; the token is its own env var.
docker run -d -p 7777:7777 -e MCP_MODE=headless -e SOT_MCP_TOKEN=secret \
ghcr.io/fjaeckel/seriesoftubes --clock realtime --pace 60000
# Headless, with your own token
docker run -d --name sot -p 127.0.0.1:7777:7777 -e MCP_MODE=headless -e SOT_MCP_TOKEN=secret \
ghcr.io/fjaeckel/seriesoftubes:$V --clock realtime --pace 60000
claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp --header "Authorization: Bearer secret"
# The browser session: open http://localhost:8080, then Settings → Agent API.
docker run -d -p 8080:8080 -p 7777:7777 ghcr.io/fjaeckel/seriesoftubes
# The browser session: open http://localhost:8080, then Settings → Agent API. The token is in `docker logs sot`.
docker run -d --name sot -p 127.0.0.1:8080:8080 -p 127.0.0.1:7777:7777 ghcr.io/fjaeckel/seriesoftubes:$V
```
`load_save` and `export_save` take JSON only unless the server runs with `--save-dir`; mount a volume for it:
`load_save` and `export_save` take JSON only unless the server runs with `--save-dir`; the image has `/saves` for it,
owned by the server's user, so mount a volume there:
```sh
docker run -d -p 7777:7777 -e MCP_MODE=headless -v sot-saves:/saves \
ghcr.io/fjaeckel/seriesoftubes --save-dir /saves
docker run -d -p 127.0.0.1:7777:7777 -e MCP_MODE=headless -e SOT_MCP_TOKEN=secret -v sot-saves:/saves \
ghcr.io/fjaeckel/seriesoftubes:$V --save-dir /saves
```
What "Over HTTP" says applies to the container too: the mapped port is reachable by anything that can reach the host,
so set a token before exposing one, and there is no TLS.
The image's Node base is pinned by digest, its dependencies by the lockfile, and every workflow action by commit;
Dependabot (`.github/dependabot.yml`) keeps them current. Pull requests that touch the image build it and try both modes
without publishing.
## The clock

View file

@ -41,6 +41,9 @@ Anything that needs data at runtime fetches it from the same origin as a static
what is cached for offline play, versioned by the release.
- **Deploys only come from releases.** `release.yml` is the only workflow with `pages: write`. Pushes to
`main` never deploy.
- **Tools are not hosting.** `npm run dev`, the MCP server and the container image that packages them
(`docker/`, published to GHCR for releases) are tools. What someone serves with them is theirs; seriesoftub.es is
the game, and nothing is ever deployed anywhere but GitHub Pages.
- **Tests guard it.** `tests/pages.test.js` checks that a build is plain static files that GitHub
Pages can serve as they are: no server or host configuration files, every local reference resolving
inside `_site/`, nothing over the size limits, `CNAME` and `404.html` in place, and the deploy going