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

@ -35,6 +35,9 @@ one, redesign the feature.
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

View file

@ -1,4 +1,10 @@
.git
.github
node_modules
_site
# The image takes only what docker/Dockerfile copies; everything else (git history, tests, docs, local saves,
# node_modules, _site) stays out of the build context.
*
!package.json
!package-lock.json
!src/
!site/
!scripts/
!tests/harness.js
!docker/docker-entrypoint.sh

39
.github/dependabot.yml vendored Normal file
View file

@ -0,0 +1,39 @@
# Keeps what the workflows and the container image pin up to date: every GitHub Action is pinned to a commit SHA
# (Dependabot moves the SHA and its version comment together), the image's Node base to a digest, and the npm tools
# to the lockfile. Updates come as pull requests, one group per ecosystem, once a week.
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
day: monday
groups:
actions:
patterns: ["*"]
commit-message:
prefix: "CI"
- package-ecosystem: docker
directory: /docker
schedule:
interval: weekly
day: monday
# The image runs the Node major CI tests on (ci.yml); a new major comes with CI, by hand.
ignore:
- dependency-name: node
update-types: ["version-update:semver-major"]
commit-message:
prefix: "Container"
- package-ecosystem: npm
directory: /
schedule:
interval: weekly
day: monday
groups:
tools:
patterns: ["*"]
update-types: [minor, patch]
commit-message:
prefix: "Tools"

View file

@ -25,10 +25,10 @@ jobs:
env:
GH_TOKEN: ${{ github.token }}
steps:
- uses: actions/checkout@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
- uses: actions/setup-node@v7
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
cache: npm

View file

@ -26,8 +26,8 @@ jobs:
matrix:
part: [1, 2, 3, 4]
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
cache: npm
@ -38,8 +38,8 @@ jobs:
name: build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
cache: npm
@ -61,8 +61,8 @@ jobs:
translations:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
cache: npm

View file

@ -27,9 +27,9 @@ jobs:
id-token: write
actions: read
steps:
- uses: actions/checkout@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 1
- uses: anthropics/claude-code-action@v1
- uses: anthropics/claude-code-action@c0949c50a78c1ec8ce2647db36629b870e715d0c # v1.0.268
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

View file

@ -1,72 +1,164 @@
name: Build and push Docker image
name: Container image
# Every push to main publishes :latest and :<sha>. A release publishes :<version>
# built from its tag: auto-release.yml dispatches this workflow alongside the Pages
# deploy, because releases created with the workflow token do not fire the
# "released" event. Hand-published releases fire it directly.
# Publishes ghcr.io/<owner>/<repo>:<version> for releases, and nothing else: auto-release.yml dispatches this workflow
# with the new tag (pre-releases too). There is no :latest and no image per commit. Pushes and pull requests that change
# what goes into the image only build it and try both modes; they never publish. The image packages the MCP server and
# the development server; the game itself is hosted on GitHub Pages only (docs/adr/0001-github-pages-only.md).
on:
push:
branches: [main]
release:
types: [released, prereleased]
workflow_dispatch:
inputs:
tag:
description: Existing release tag to build (e.g. v2.10.0); empty builds main
required: false
description: Release tag to build and publish (e.g. v2.10.1)
required: true
push:
branches: [main]
paths:
- docker/**
- .dockerignore
- package.json
- package-lock.json
- scripts/**
- tests/harness.js
- .github/workflows/docker.yml
pull_request:
paths:
- docker/**
- .dockerignore
- package.json
- package-lock.json
- scripts/**
- tests/harness.js
- .github/workflows/docker.yml
permissions:
contents: read
packages: write
concurrency:
group: docker-${{ github.event_name }}-${{ inputs.tag || github.ref }}
cancel-in-progress: ${{ github.event_name != 'workflow_dispatch' }}
jobs:
build:
test:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- name: Checkout
uses: actions/checkout@v4
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.release.tag_name || inputs.tag }}
ref: ${{ inputs.tag || '' }}
persist-credentials: false
- name: Work out the image tags
id: tags
env:
TAG: ${{ github.event.release.tag_name || inputs.tag }}
- uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
- name: Build for this runner
uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
with:
context: .
file: docker/Dockerfile
platforms: linux/amd64
load: true
push: false
tags: sot:test
cache-from: type=gha
cache-to: type=gha,mode=max
- name: Try both modes
run: |
set -euo pipefail
# The image is named after this repository (ghcr.io/<owner>/<repo>, lowercased).
image=ghcr.io/${GITHUB_REPOSITORY,,}
if [ -n "$TAG" ]; then
want="v$(jq -r .version package.json)"
if [ "$TAG" != "$want" ]; then
echo "::error::Release tag $TAG does not match package.json version ($want)"
exit 1
fi
echo "tags=$image:${TAG#v}" >> "$GITHUB_OUTPUT"
else
echo "tags=$image:latest,$image:$GITHUB_SHA" >> "$GITHUB_OUTPUT"
fi
init='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"ci","version":"1"}}}'
mcp() { curl -sS -o /tmp/out -w '%{http_code}' -X POST http://127.0.0.1:7777/mcp \
-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' "$@" -d "$init"; }
until_up() { for i in $(seq 1 60); do curl -s -o /dev/null "$1" && return 0; sleep 1; done; docker logs "$2"; exit 1; }
- name: Set up QEMU
uses: docker/setup-qemu-action@v3
# Headless, with a token: refused without it, answered with it.
docker run -d --name h -p 127.0.0.1:7777:7777 -e MCP_MODE=headless -e SOT_MCP_TOKEN=ci-token sot:test
until_up http://127.0.0.1:7777/ h
test "$(mcp)" = 401
test "$(mcp -H 'authorization: Bearer ci-token')" = 200
grep -q serverInfo /tmp/out
docker rm -f h
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
# No token given: the container makes one, says so, and wants it.
docker run -d --name t -p 127.0.0.1:7777:7777 -e MCP_MODE=headless sot:test
until_up http://127.0.0.1:7777/ t
test "$(mcp)" = 401
tok=$(docker logs t 2>&1 | sed -n "s/.*this run's token is //p" | head -1)
test -n "$tok"
test "$(mcp -H "authorization: Bearer $tok")" = 200
docker rm -f t
- name: Log in to GitHub Container Registry
uses: docker/login-action@v3
# Browser mode: the development page and the MCP server.
docker run -d --name b -p 127.0.0.1:8080:8080 -p 127.0.0.1:7777:7777 -e SOT_MCP_TOKEN=ci-token sot:test
until_up http://127.0.0.1:8080/ b
test "$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8080/)" = 200
until_up http://127.0.0.1:7777/ b
test "$(mcp -H 'authorization: Bearer ci-token')" = 200
docker rm -f b
# The server runs as node, not root.
test "$(docker run --rm --entrypoint id sot:test -u)" != 0
publish:
if: github.event_name == 'workflow_dispatch'
needs: test
runs-on: ubuntu-latest
timeout-minutes: 45
permissions:
contents: read
packages: write
steps:
- name: Check the tag
env:
TAG: ${{ inputs.tag }}
run: |
[[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$ ]] || { echo "::error::Not a release tag: $TAG"; exit 1; }
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ inputs.tag }}
persist-credentials: false
- name: Work out the image name and version
id: meta
env:
TAG: ${{ inputs.tag }}
run: |
set -euo pipefail
want="v$(jq -r .version package.json)"
if [ "$TAG" != "$want" ]; then echo "::error::Release tag $TAG does not match package.json ($want)"; exit 1; fi
# Named after this repository (ghcr.io/<owner>/<repo>, lowercased), so forks publish their own.
echo "image=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
echo "revision=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
echo "created=$(git log -1 --format=%cI)" >> "$GITHUB_OUTPUT"
- uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
- uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
- uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push
uses: docker/build-push-action@v6
- name: Build and push the release's version
uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
with:
context: .
file: docker/Dockerfile
platforms: linux/amd64,linux/arm64
push: true
tags: ${{ steps.tags.outputs.tags }}
tags: ${{ steps.meta.outputs.image }}:${{ steps.meta.outputs.version }}
labels: |
org.opencontainers.image.title=Series of Tubes MCP server
org.opencontainers.image.description=The Series of Tubes MCP server and development server, so an AI client can play the game.
org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
org.opencontainers.image.documentation=${{ github.server_url }}/${{ github.repository }}/blob/${{ inputs.tag }}/docs/MCP.md
org.opencontainers.image.version=${{ steps.meta.outputs.version }}
org.opencontainers.image.revision=${{ steps.meta.outputs.revision }}
org.opencontainers.image.created=${{ steps.meta.outputs.created }}
org.opencontainers.image.licenses=MIT
provenance: mode=max
sbom: true
cache-from: type=gha
cache-to: type=gha,mode=max

View file

@ -17,7 +17,7 @@ jobs:
if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
runs-on: ubuntu-latest
steps:
- uses: actions/download-artifact@v4
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
name: perf
run-id: ${{ github.event.workflow_run.id }}

View file

@ -22,8 +22,8 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 40
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
cache: npm
@ -48,7 +48,7 @@ jobs:
env:
PR: ${{ github.event.pull_request.number }}
run: echo "$PR" > pr-number.txt
- uses: actions/upload-artifact@v4
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
if: github.event_name == 'pull_request'
with:
name: perf

View file

@ -42,10 +42,10 @@ jobs:
ALLOW_OLDER: ${{ inputs.allow_older || false }}
GH_TOKEN: ${{ github.token }}
steps:
- uses: actions/checkout@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ env.TAG }}
- uses: actions/setup-node@v7
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
cache: npm
@ -100,7 +100,7 @@ jobs:
run: npm test -- tests/weekly-puzzle.test.js tests/puzzles.test.js $(ls tests/weekly-scenario.test.js tests/weekly-architect.test.js 2>/dev/null)
- name: Build site
run: VERSION="${TAG#v}" REQUIRE_NOTES=1 npm run build
- uses: actions/upload-pages-artifact@v5
- uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: ./_site
@ -115,9 +115,7 @@ jobs:
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@v5
# Tell IndexNow (Bing, Yandex, Seznam, …) about the new version, only after
uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
# the site is live.
indexnow:
needs: deploy

View file

@ -38,10 +38,10 @@ jobs:
GH_TOKEN: ${{ github.token }}
KEY: ${{ inputs.key }}
steps:
- uses: actions/checkout@v7
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: main
- uses: actions/setup-node@v7
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 24
cache: npm

View file

@ -1,16 +1,28 @@
FROM node:26-slim
# The MCP server and the development server in one image (docs/MCP.md, "In a container"). docker.yml builds it and
# publishes it to GHCR for releases only; nothing here is ever deployed to GitHub Pages (docs/adr/0001-github-pages-only.md).
# The base is pinned by digest and kept current by Dependabot (.github/dependabot.yml); CI tests on the same Node major.
FROM node:24-slim@sha256:01d566e8d94d8c619591d78652babfccd3c6992a3dffa9ed5ab39e11cf6c70e9
COPY . /series-of-tubes
WORKDIR /series-of-tubes
RUN npm install
# Dependencies first, exactly as locked, so a change to the code reuses this layer. Every dependency is a dev one (the
# game has none), and the servers need them all. No install scripts run.
COPY package.json package-lock.json ./
RUN npm ci --no-audit --no-fund --ignore-scripts && npm cache clean --force
COPY docker/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh \
&& chown -R node:node /series-of-tubes
# Only what the servers read: the game's source and static files, the scripts, and the harness the MCP server plays
# through. Owned by root and read-only to the server, which runs as node.
COPY src ./src
COPY site ./site
COPY scripts ./scripts
COPY tests/harness.js ./tests/harness.js
COPY --chmod=0755 docker/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
# --save-dir /saves needs somewhere the server may write: a volume mounted here takes this ownership.
RUN mkdir /saves && chown node:node /saves
VOLUME /saves
USER node
ENV NPM_CONFIG_UPDATE_NOTIFIER=false
EXPOSE 8080 7777
ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]

View file

@ -1,42 +1,55 @@
#!/usr/bin/env bash
set -u
# Starts the container's servers (docker/Dockerfile, docs/MCP.md "In a container").
# MCP_MODE=browser (default): the development server on :8080, with the relay a player's tab dials, and the MCP server
# on :7777 driving that tab.
# MCP_MODE=headless: only the MCP server, with a game of its own.
# Everything after the image name goes to scripts/mcp.js (node scripts/mcp.js --help lists the options).
set -uo pipefail
cd /series-of-tubes
# MCP_MODE picks what runs: browser (default) serves the game page and relays the
# player's tab to the MCP server; headless runs a game of its own, no page needed.
mode=${MCP_MODE:-browser}
case "$mode" in
browser|headless) ;;
*) echo "[entrypoint] MCP_MODE must be browser or headless, not '$mode'" >&2; exit 1 ;;
esac
# Everything after the image name is passed to the MCP server as well
# (node scripts/mcp.js --help lists the options).
extra=("$@")
has() { local a; for a in "${extra[@]}"; do [ "$a" = "$1" ] && return 0; done; return 1; }
# A container needs 0.0.0.0 to be reachable at all; default --http unless given.
# A container must listen beyond loopback to be reachable at all; --http in the arguments overrides it.
http=(--http 0.0.0.0:7777)
for a in "${extra[@]}"; do [ "$a" = --http ] && http=(); done
has --http && http=()
# Listening beyond loopback, the MCP server would take orders from anyone who reaches the port (its Host check stops
# browsers, not other clients), so it gets a token. None given (SOT_MCP_TOKEN or --token-file): this run makes one and
# prints it. MCP_NO_TOKEN=1 turns that off, for a port published to 127.0.0.1 only.
if [ -z "${SOT_MCP_TOKEN:-}" ] && ! has --token-file && [ "${MCP_NO_TOKEN:-}" != 1 ]; then
SOT_MCP_TOKEN=$(node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('base64url'))")
export SOT_MCP_TOKEN
echo "[entrypoint] No SOT_MCP_TOKEN given: this run's token is $SOT_MCP_TOKEN" >&2
echo "[entrypoint] claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp --header \"Authorization: Bearer $SOT_MCP_TOKEN\"" >&2
fi
pids=()
start() { "$@" & pids+=("$!"); }
shutdown() {
trap '' TERM INT
kill -TERM "${pids[@]}" 2>/dev/null
wait "${pids[@]}" 2>/dev/null
exit 0
kill -TERM "${pids[@]}" 2>/dev/null || true
wait "${pids[@]}" 2>/dev/null || true
exit "${1:-0}"
}
trap shutdown TERM INT
# node directly, not npm run: one process less, and signals reach the server.
if [ "$mode" = browser ]; then
start npm run dev -- --host 0.0.0.0 --port 8080
start npm run mcp -- --browser "${http[@]}" "${extra[@]}"
start node scripts/dev.js --host 0.0.0.0 --port 8080
start node scripts/mcp.js --browser "${http[@]}" "${extra[@]}"
else
start npm run mcp -- "${http[@]}" "${extra[@]}"
start node scripts/mcp.js "${http[@]}" "${extra[@]}"
fi
# One server stopping stops the container, with its status, so a restart policy can bring both back.
status=0
wait -n || status=$?
echo "[entrypoint] a process exited with status $status; stopping the container" >&2
shutdown
echo "[entrypoint] a server exited with status $status; stopping the container" >&2
shutdown "$status"

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

78
tests/docker.test.js Normal file
View file

@ -0,0 +1,78 @@
// The container image and the workflows that build things: what is published, how, and that every third-party piece is
// pinned. The image goes to GHCR for releases only (no :latest, no image per commit), never to Pages; it runs as node,
// from a base pinned by digest, with only what the servers read; its MCP server gets a token unless told otherwise; every
// GitHub Action is pinned to a commit; Dependabot keeps all of it current. docs/MCP.md, "In a container".
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const path = require('node:path');
const ROOT = path.join(__dirname, '..');
const read = (p) => fs.readFileSync(path.join(ROOT, p), 'utf8');
// Without comments: what a file says about itself is not what it does.
const code = (p) => read(p).split('\n').map((l) => l.replace(/(^|\s)#.*$/, '')).join('\n');
const WF = path.join(ROOT, '.github', 'workflows');
test('every GitHub Action in every workflow is pinned to a commit, with its version beside it', () => {
const loose = [];
for (const f of fs.readdirSync(WF).filter((f) => /\.ya?ml$/.test(f)))
for (const [i, line] of read(`.github/workflows/${f}`).split('\n').entries()) {
const m = /^\s*(?:-\s*)?uses:\s*(\S+)(.*)$/.exec(line);
if (!m || m[1].startsWith('./')) continue;
if (!/^[\w.-]+\/[\w./-]+@[0-9a-f]{40}$/.test(m[1]) || !/#\s*v\d+(\.\d+)*/.test(m[2])) loose.push(`${f}:${i + 1} ${m[1]}`);
}
assert.deepEqual(loose, []);
});
test('Dependabot keeps the actions, the image’s base and the npm tools current', () => {
const d = read('.github/dependabot.yml');
for (const [eco, dir] of [['github-actions', '/'], ['docker', '/docker'], ['npm', '/']])
assert.match(d, new RegExp(`package-ecosystem: ${eco}\\s+directory: ${dir.replace('/', '\\/')}\\n`), eco);
});
test('the image is published for releases only, as their version, never as latest', () => {
const w = code('.github/workflows/docker.yml');
assert.doesNotMatch(w, /:latest\b|\blatest\b.*tags|tags:.*latest/, 'no latest');
assert.doesNotMatch(w, /\$GITHUB_SHA|github\.sha\b.*tags/, 'no image per commit');
assert.doesNotMatch(w, /^\s+release:/m, 'releases dispatch it; the release event does not');
// Only the publish job may push or hold packages: write, and it runs only when a release dispatches it.
const pub = w.slice(w.indexOf('\n publish:'));
const tst = w.slice(w.indexOf('\n test:'), w.indexOf('\n publish:'));
assert.match(pub, /if: github\.event_name == 'workflow_dispatch'/);
assert.match(pub, /needs: test/, 'only an image that passed the smoke test');
assert.match(pub, /push: true/);
assert.match(pub, /tags: \$\{\{ steps\.meta\.outputs\.image \}\}:\$\{\{ steps\.meta\.outputs\.version \}\}\n/, 'one tag: the version');
assert.match(pub, /does not match package\.json/, 'the tag must be the release in package.json');
assert.doesNotMatch(tst, /push: true|packages: write/, 'the test job never publishes');
assert.match(w, /^permissions:\n {2}contents: read\n/m, 'read-only unless publishing');
assert.doesNotMatch(w, /pages: write|deploy-pages/, 'never to Pages');
// auto-release.yml is what dispatches it, with the new tag.
assert.match(read('.github/workflows/auto-release.yml'), /gh workflow run docker\.yml [^\n]*-f tag=/);
});
test('the image: pinned base, locked dependencies, only what the servers need, not root', () => {
const d = code('docker/Dockerfile');
assert.match(d, /^FROM node:\d+-slim@sha256:[0-9a-f]{64}$/m, 'the base is pinned by digest');
const nodeMajor = /FROM node:(\d+)/.exec(d)[1];
for (const m of read('.github/workflows/ci.yml').matchAll(/node-version: (\d+)/g)) assert.equal(m[1], nodeMajor, 'the Node major CI tests on');
assert.match(d, /npm ci\b/); assert.doesNotMatch(d, /npm install\b/);
assert.ok(d.indexOf('COPY package.json package-lock.json') < d.indexOf('npm ci') && d.indexOf('npm ci') < d.indexOf('COPY src'), 'dependencies are their own layer');
assert.doesNotMatch(d, /^COPY \. /m, 'not the whole repository');
assert.doesNotMatch(d, /chown -R/, 'no second copy of every file just to change its owner');
assert.match(d, /^USER node$/m);
const ig = read('.dockerignore').split('\n').filter((l) => l && !l.startsWith('#'));
assert.equal(ig[0], '*', 'the build context is an allow-list');
for (const m of d.matchAll(/^COPY (?:--\S+ )*(\S+)/gm)) if (m[1] !== 'package.json') assert.ok(ig.includes('!' + m[1]) || ig.includes('!' + m[1] + '/'), `${m[1]} is let into the context`);
});
test('the entrypoint: both modes, a token unless told otherwise, and the servers run directly', () => {
const e = code('docker/docker-entrypoint.sh');
assert.match(e, /browser\|headless/);
assert.match(e, /SOT_MCP_TOKEN=\$\(node -e/, 'makes a token when none is given');
assert.match(e, /MCP_NO_TOKEN/, 'and can be told not to');
assert.match(e, /start node scripts\/dev\.js --host 0\.0\.0\.0 --port 8080/);
assert.match(e, /start node scripts\/mcp\.js --browser/);
assert.doesNotMatch(e, /npm run/);
// Every file the image's servers load at start is in the image.
for (const f of ['scripts/mcp.js', 'scripts/dev.js', 'tests/harness.js', 'scripts/lib/page.js']) assert.ok(fs.existsSync(path.join(ROOT, f)), f);
});