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:
parent
9c8cda44c1
commit
98735eb769
16 changed files with 367 additions and 110 deletions
51
docs/MCP.md
51
docs/MCP.md
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue