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 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 never depends on them. Their code stays out of `_site/` (`src/agent/` is development-only, see
`docs/adr/0004-dev-only-code.md`). `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 ## How it deploys

View file

@ -1,4 +1,10 @@
.git # The image takes only what docker/Dockerfile copies; everything else (git history, tests, docs, local saves,
.github # node_modules, _site) stays out of the build context.
node_modules *
_site !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: env:
GH_TOKEN: ${{ github.token }} GH_TOKEN: ${{ github.token }}
steps: steps:
- uses: actions/checkout@v7 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: with:
fetch-depth: 0 fetch-depth: 0
- uses: actions/setup-node@v7 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with: with:
node-version: 24 node-version: 24
cache: npm cache: npm

View file

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

View file

@ -27,9 +27,9 @@ jobs:
id-token: write id-token: write
actions: read actions: read
steps: steps:
- uses: actions/checkout@v7 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: with:
fetch-depth: 1 fetch-depth: 1
- uses: anthropics/claude-code-action@v1 - uses: anthropics/claude-code-action@c0949c50a78c1ec8ce2647db36629b870e715d0c # v1.0.268
with: with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} 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> # Publishes ghcr.io/<owner>/<repo>:<version> for releases, and nothing else: auto-release.yml dispatches this workflow
# built from its tag: auto-release.yml dispatches this workflow alongside the Pages # with the new tag (pre-releases too). There is no :latest and no image per commit. Pushes and pull requests that change
# deploy, because releases created with the workflow token do not fire the # what goes into the image only build it and try both modes; they never publish. The image packages the MCP server and
# "released" event. Hand-published releases fire it directly. # the development server; the game itself is hosted on GitHub Pages only (docs/adr/0001-github-pages-only.md).
on: on:
push:
branches: [main]
release:
types: [released, prereleased]
workflow_dispatch: workflow_dispatch:
inputs: inputs:
tag: tag:
description: Existing release tag to build (e.g. v2.10.0); empty builds main description: Release tag to build and publish (e.g. v2.10.1)
required: false 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: permissions:
contents: read contents: read
packages: write
concurrency:
group: docker-${{ github.event_name }}-${{ inputs.tag || github.ref }}
cancel-in-progress: ${{ github.event_name != 'workflow_dispatch' }}
jobs: jobs:
build: test:
runs-on: ubuntu-latest runs-on: ubuntu-latest
timeout-minutes: 20
steps: steps:
- name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
uses: actions/checkout@v4
with: with:
ref: ${{ github.event.release.tag_name || inputs.tag }} ref: ${{ inputs.tag || '' }}
persist-credentials: false
- name: Work out the image tags - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
id: tags
env: - name: Build for this runner
TAG: ${{ github.event.release.tag_name || inputs.tag }} 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
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; }
# 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
# 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
# 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: | run: |
set -euo pipefail 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)" want="v$(jq -r .version package.json)"
if [ "$TAG" != "$want" ]; then if [ "$TAG" != "$want" ]; then echo "::error::Release tag $TAG does not match package.json ($want)"; exit 1; fi
echo "::error::Release tag $TAG does not match package.json version ($want)" # Named after this repository (ghcr.io/<owner>/<repo>, lowercased), so forks publish their own.
exit 1 echo "image=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
fi echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
echo "tags=$image:${TAG#v}" >> "$GITHUB_OUTPUT" echo "revision=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
else echo "created=$(git log -1 --format=%cI)" >> "$GITHUB_OUTPUT"
echo "tags=$image:latest,$image:$GITHUB_SHA" >> "$GITHUB_OUTPUT"
fi
- name: Set up QEMU - uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
uses: docker/setup-qemu-action@v3
- name: Set up Docker Buildx - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
uses: docker/setup-buildx-action@v3
- name: Log in to GitHub Container Registry - uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0
uses: docker/login-action@v3
with: with:
registry: ghcr.io registry: ghcr.io
username: ${{ github.actor }} username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }} password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push - name: Build and push the release's version
uses: docker/build-push-action@v6 uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
with: with:
context: . context: .
file: docker/Dockerfile file: docker/Dockerfile
platforms: linux/amd64,linux/arm64 platforms: linux/amd64,linux/arm64
push: true 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-from: type=gha
cache-to: type=gha,mode=max 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' if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- uses: actions/download-artifact@v4 - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with: with:
name: perf name: perf
run-id: ${{ github.event.workflow_run.id }} run-id: ${{ github.event.workflow_run.id }}

View file

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

View file

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

View file

@ -38,10 +38,10 @@ jobs:
GH_TOKEN: ${{ github.token }} GH_TOKEN: ${{ github.token }}
KEY: ${{ inputs.key }} KEY: ${{ inputs.key }}
steps: steps:
- uses: actions/checkout@v7 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with: with:
ref: main ref: main
- uses: actions/setup-node@v7 - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with: with:
node-version: 24 node-version: 24
cache: npm 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 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 # Only what the servers read: the game's source and static files, the scripts, and the harness the MCP server plays
RUN chmod +x /usr/local/bin/docker-entrypoint.sh \ # through. Owned by root and read-only to the server, which runs as node.
&& chown -R node:node /series-of-tubes 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 USER node
ENV NPM_CONFIG_UPDATE_NOTIFIER=false
EXPOSE 8080 7777 EXPOSE 8080 7777
ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"] ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]

View file

@ -1,42 +1,55 @@
#!/usr/bin/env bash #!/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 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} mode=${MCP_MODE:-browser}
case "$mode" in case "$mode" in
browser|headless) ;; browser|headless) ;;
*) echo "[entrypoint] MCP_MODE must be browser or headless, not '$mode'" >&2; exit 1 ;; *) echo "[entrypoint] MCP_MODE must be browser or headless, not '$mode'" >&2; exit 1 ;;
esac esac
# Everything after the image name is passed to the MCP server as well
# (node scripts/mcp.js --help lists the options).
extra=("$@") 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) 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=() pids=()
start() { "$@" & pids+=("$!"); } start() { "$@" & pids+=("$!"); }
shutdown() { shutdown() {
trap '' TERM INT trap '' TERM INT
kill -TERM "${pids[@]}" 2>/dev/null kill -TERM "${pids[@]}" 2>/dev/null || true
wait "${pids[@]}" 2>/dev/null wait "${pids[@]}" 2>/dev/null || true
exit 0 exit "${1:-0}"
} }
trap shutdown TERM INT trap shutdown TERM INT
# node directly, not npm run: one process less, and signals reach the server.
if [ "$mode" = browser ]; then if [ "$mode" = browser ]; then
start npm run dev -- --host 0.0.0.0 --port 8080 start node scripts/dev.js --host 0.0.0.0 --port 8080
start npm run mcp -- --browser "${http[@]}" "${extra[@]}" start node scripts/mcp.js --browser "${http[@]}" "${extra[@]}"
else else
start npm run mcp -- "${http[@]}" "${extra[@]}" start node scripts/mcp.js "${http[@]}" "${extra[@]}"
fi fi
# One server stopping stops the container, with its status, so a restart policy can bring both back.
status=0 status=0
wait -n || status=$? wait -n || status=$?
echo "[entrypoint] a process exited with status $status; stopping the container" >&2 echo "[entrypoint] a server exited with status $status; stopping the container" >&2
shutdown shutdown "$status"

View file

@ -79,36 +79,49 @@ claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp
### In a container ### In a container
Every push to `main` and every release publishes a multi-arch (amd64/arm64) image at Every release publishes a multi-arch (amd64/arm64) image at `ghcr.io/fjaeckel/seriesoftubes:<version>`
`ghcr.io/fjaeckel/seriesoftubes`, built from the repo by the `docker.yml` workflow: `latest` and the commit SHA on (`docker.yml`, dispatched by the release; pre-releases too). There is no `latest` and no image per commit: pick a
pushes, the release's version (pre-releases included) on releases. It packages the dev server and the MCP server; version from the [releases](https://github.com/fjaeckel/seriesoftubes/releases). It holds the MCP server and the
`node scripts/mcp.js --help` options go after the image name, and `--http 0.0.0.0:7777` is the default (a container development server, nothing else from the repository, and runs as `node`, not root. It is published to GHCR only; the
bound to loopback would be unreachable; pass your own `--http` to override). 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 - **`MCP_MODE=browser`** (the default) serves the development page on 8080, with the relay, and runs the MCP server on
development page so a browser tab can play it, as above. 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 ```sh
docker run -d -p 7777:7777 -e MCP_MODE=headless ghcr.io/fjaeckel/seriesoftubes V=2.10.1 # a release
claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp
# Options are passed to scripts/mcp.js; the token is its own env var. # Headless, with your own token
docker run -d -p 7777:7777 -e MCP_MODE=headless -e SOT_MCP_TOKEN=secret \ 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 --clock realtime --pace 60000 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. # The browser session: open http://localhost:8080, then Settings → Agent API. The token is in `docker logs sot`.
docker run -d -p 8080:8080 -p 7777:7777 ghcr.io/fjaeckel/seriesoftubes 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 ```sh
docker run -d -p 7777:7777 -e MCP_MODE=headless -v sot-saves:/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 --save-dir /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, The image's Node base is pinned by digest, its dependencies by the lockfile, and every workflow action by commit;
so set a token before exposing one, and there is no TLS. Dependabot (`.github/dependabot.yml`) keeps them current. Pull requests that touch the image build it and try both modes
without publishing.
## The clock ## 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. 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 - **Deploys only come from releases.** `release.yml` is the only workflow with `pages: write`. Pushes to
`main` never deploy. `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 - **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 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 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);
});