Let a container keep itself current by running from a checkout on its volume

The self-updater shipped in 0.4.0 can move a git checkout but not an image,
so a board on Railway — including bbs.hqtui.com — only ever saw the "new
version available" notice. This gives the image a way to be updated from
the inside.

With TSBB_CHECKOUT_DIR pointing into a volume, the container clones the
repository there on first boot, at the image's own commit, and installs its
dependencies from the image's pnpm store, so the first start takes about
three seconds and needs no download. It then runs the server from that
checkout in a loop: the updater fetches each release into the volume and
exits, and the loop starts the new code. A container restart comes back on
the release it had rather than the image it was built from, because the
checkout is on the volume.

Without TSBB_CHECKOUT_DIR the entrypoint runs the image's own code exactly
as before, so tsbb.dev is unchanged.

Copying the image's node_modules into the checkout instead of installing
does not work — pnpm sees a tree made for another path and stops to ask
whether it may rebuild it, and there is no TTY to say yes. Linking from the
store is what the install already does, and it is as fast.

Tried for real in Docker: a container seeded at the commit before the 0.4.0
bump found v0.4.0 a minute after boot, fetched, checked out, installed in
one second, restarted, and answered the healthcheck on the new commit. A
restart of that container came back on 0.4.0.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PY5Y9gpnQ9kevUFwXJakyn

Author: ralyodio

Dockerfile

@@ -9,6 +9,13 @@ ENV NODE_ENV=production \
 
 RUN corepack enable
 
+# git is for a container that runs from a checkout on a volume and updates
+# itself (TSBB_CHECKOUT_DIR — see bin/entrypoint.sh). An image without it can
+# only ever be replaced by another image.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
 # The whole tree is copied before installing rather than listing each workspace
 # manifest by hand. Listing them is faster to rebuild and silently wrong: a new
 # package is invisible to pnpm until it happens to gain an external dependency.
@@ -23,5 +30,7 @@ RUN pnpm install --frozen-lockfile --ignore-scripts
 EXPOSE 3000
 
 # Migrations run at boot inside the server, so a deploy can never leave new code
-# running against an old schema.
-CMD ["node", "apps/server/src/index.ts"]
+# running against an old schema. The entrypoint runs the image's own code
+# unless TSBB_CHECKOUT_DIR says to run — and keep updating — a checkout on a
+# volume instead.
+CMD ["sh", "bin/entrypoint.sh"]

README.md

@@ -267,6 +267,7 @@ one with a fresh session secret and whatever you already had set.
 | `TSBB_UPDATES` | on | Set to `off` and the board never checks for a release |
 | `TSBB_RESTART` | `respawn` | `exit` under a supervisor that restarts the process itself |
 | `TSBB_UPDATE_REPO` | `profullstack/tsbb` | A fork that publishes its own releases |
+| `TSBB_CHECKOUT_DIR` | — | A directory on a volume; the container runs, and updates, a checkout there |
 
 The worker runs inside the server by default, so email works from one command.
 
@@ -284,10 +285,19 @@ out, and a **Check now** button; with automatic updates off it also offers
 **Update now**, and `tsbb update` does the same from a shell.
 
 Two things it will not do. It never touches a checkout with local changes —
-that is somebody's work, and it stops and says so. And it never updates a
-container: the Docker image has no `.git` to move, so a board on Railway, Fly
-or a plain `docker run` sees the notice and is updated by redeploying the image,
-which is how those platforms expect it anyway.
+that is somebody's work, and it stops and says so. And it never updates an
+image: the Docker image has no `.git` to move, so a board running the image's
+own code sees the notice and is updated by redeploying, which is how those
+platforms expect it anyway.
+
+A container *can* keep itself current if it has a volume. Set
+`TSBB_CHECKOUT_DIR` to a directory on it (`/app/data/app`, say) and the
+container clones the repository there on first boot — at the image's own
+commit, with dependencies linked from the image's package store, so the first
+start is as fast as any other — and runs from that checkout instead. Each release is then
+fetched into the volume and the server restarted from it, and a container
+restart comes back on the release it had, not the image it was built from.
+`bbs.hqtui.com` runs this way.
 
 On restart the board spawns a fresh copy of itself with the same command line
 and exits, so `pnpm start` in a terminal or under nohup carries on with the new

bin/entrypoint.sh

@@ -0,0 +1,63 @@
+#!/bin/sh
+#
+# How the container starts.
+#
+# With no TSBB_CHECKOUT_DIR it runs the code baked into the image, which is
+# what an image is for: it is updated by building and deploying a new one.
+#
+# With TSBB_CHECKOUT_DIR pointing into a volume, the container instead keeps a
+# git checkout THERE and runs from it. On first boot it clones the repository
+# at the image's own commit and installs from the image's own package store,
+# so the first start needs no download and passes the healthcheck like any
+# other. From then on the board updates itself: the server fetches each new
+# release into the checkout, exits, and this script starts it again from the
+# new code — so a board on a platform that only redeploys images still follows
+# releases within minutes, and survives a container restart because the
+# checkout is on the volume, not in the container.
+set -eu
+
+IMAGE_ROOT="${TSBB_IMAGE_ROOT:-/app}"
+DIR="${TSBB_CHECKOUT_DIR:-}"
+REPO="${TSBB_UPDATE_REPO:-profullstack/tsbb}"
+
+if [ -z "$DIR" ]; then
+  cd "$IMAGE_ROOT"
+  exec node apps/server/src/index.ts
+fi
+
+if [ ! -d "$DIR/.git" ]; then
+  echo "[tsbb] first boot: cloning $REPO into $DIR"
+  rm -rf "$DIR"
+  git clone --quiet "https://github.com/$REPO" "$DIR"
+  # Start from exactly the commit this image was built from, so the checkout
+  # and the image agree, so the install below finds everything in the store.
+  if [ -n "${RAILWAY_GIT_COMMIT_SHA:-}" ]; then
+    git -C "$DIR" -c advice.detachedHead=false checkout --quiet "$RAILWAY_GIT_COMMIT_SHA" \
+      || echo "[tsbb] commit ${RAILWAY_GIT_COMMIT_SHA} is not in the clone; staying on the default branch"
+  fi
+  # The image's install left every package in pnpm's store, so linking them
+  # into the new checkout is seconds and needs no network. Copying the image's
+  # node_modules instead does not work: pnpm sees a tree made for another path
+  # and stops to ask whether it may rebuild it. CI=true is the "yes" it wants
+  # if the lockfile has drifted and it must.
+  echo "[tsbb] installing dependencies from the image's store"
+  ( cd "$DIR" && CI=true pnpm install --frozen-lockfile --ignore-scripts --offline ) \
+    || ( cd "$DIR" && CI=true pnpm install --frozen-lockfile --ignore-scripts )
+fi
+
+cd "$DIR"
+echo "[tsbb] running from $DIR at $(git rev-parse --short HEAD) ($(git describe --tags --always 2>/dev/null))"
+
+# The updater exits after installing a release; this loop is the supervisor
+# that brings the new code up. A crash waits a few seconds so a broken build
+# cannot spin the container.
+export TSBB_RESTART=exit
+while :; do
+  if node apps/server/src/index.ts; then
+    echo "[tsbb] server exited; starting again from $(git rev-parse --short HEAD)"
+  else
+    code=$?
+    echo "[tsbb] server exited with status $code; starting again in 5s"
+    sleep 5
+  fi
+done

railway.json

@@ -5,9 +5,9 @@
     "dockerfilePath": "Dockerfile"
   },
   "deploy": {
-    "startCommand": "node apps/server/src/index.ts",
+    "startCommand": "sh bin/entrypoint.sh",
     "healthcheckPath": "/healthz",
-    "healthcheckTimeout": 120,
+    "healthcheckTimeout": 300,
     "restartPolicyType": "ON_FAILURE",
     "restartPolicyMaxRetries": 10,
     "numReplicas": 1