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
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
39
.github/dependabot.yml
vendored
Normal 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"
|
||||
4
.github/workflows/auto-release.yml
vendored
4
.github/workflows/auto-release.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
12
.github/workflows/ci.yml
vendored
12
.github/workflows/ci.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
4
.github/workflows/claude.yml
vendored
4
.github/workflows/claude.yml
vendored
|
|
@ -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 }}
|
||||
|
|
|
|||
174
.github/workflows/docker.yml
vendored
174
.github/workflows/docker.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
2
.github/workflows/perf-comment.yml
vendored
2
.github/workflows/perf-comment.yml
vendored
|
|
@ -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 }}
|
||||
|
|
|
|||
6
.github/workflows/perf.yml
vendored
6
.github/workflows/perf.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
10
.github/workflows/release.yml
vendored
10
.github/workflows/release.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
4
.github/workflows/weekly-puzzle.yml
vendored
4
.github/workflows/weekly-puzzle.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"]
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
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
|
||||
|
|
|
|||
78
tests/docker.test.js
Normal file
78
tests/docker.test.js
Normal 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);
|
||||
});
|
||||
Loading…
Add table
Add a link
Reference in a new issue