The hall comes first, in the shape of wizwar's landing

The home page is a centred card: title and pitch, your name, play the
bot or continue the duel under way, create or join a duel by code, a
sample ledger, the duels this browser holds with whose move it is, and
the story of the game. The single-player board lives at /play. The
droplet gains the duel server as a systemd service behind Caddy.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

deploy/README.md

@@ -1,16 +1,18 @@
 # Deploying Waving Hands
 
-The game runs entirely in the browser: the duel state lives in local storage
-and nothing is rendered or stored on a server. Production is therefore a
-single DigitalOcean droplet running only Caddy, which terminates TLS with
-automatic certificates and serves the static build from
-/opt/waving-hands/build. No Node, no service, no database.
+The single-player game runs entirely in the browser. Duels between people
+go through a small Node process that keeps each room as an append-only
+ledger of moves in /var/lib/waving-hands/rooms. Production is one
+DigitalOcean droplet: Caddy terminates TLS with automatic certificates,
+serves the static build from /opt/waving-hands/build, and proxies /api and
+/ws to the duel server on port 8788, which runs as the `waving-hands` user
+under systemd from /opt/waving-hands/app.
 
 ## Sizing
 
-The smallest droplet is enough: `s-1vcpu-512mb-10gb` ($4 a month). The build
-is under half a megabyte and Caddy idles in about 30 MB of memory. Move up to
-`s-1vcpu-1gb` only if the site ever gains a server side.
+The smallest droplet, `s-1vcpu-512mb-10gb` ($4 a month), carries both Caddy
+and the duel server comfortably: the server is one small Node process capped
+at 300 MB by its unit file, and a room is a few kilobytes of ledger.
 
 The zero-cost alternative is a second site block in an existing Caddy
 server's configuration pointing at a second directory; the deploy script
@@ -34,7 +36,8 @@ uptime and upgrades independent of anything else.
 2. `scp deploy/setup-droplet.sh root@<ip>:/root/ && ssh root@<ip> \
     "bash /root/setup-droplet.sh 'hands.kestrelsnest.social, waving-hands.<ip>.sslip.io'"`
    (point the A record at the new IP first, or leave the real name out until it is).
-3. `deploy/deploy.sh <ip>`
+3. `scp deploy/setup-server.sh root@<ip>:/root/ && ssh root@<ip> "bash /root/setup-server.sh"`
+4. `deploy/deploy.sh <ip>`
 
 The sslip.io hostname works with no DNS at all. To add a real name, point an
 A record at the droplet and add the name to the first line of
@@ -45,13 +48,18 @@ fetches the certificate on first request.
 
     deploy/deploy.sh <ip>
 
-Runs the type-check, the tests and the build locally, rsyncs `build/` to the
-droplet keeping the previous week's hashed assets, and reloads Caddy. A
-player mid-duel loses nothing: their game is in their own browser, and the
-next page load picks up the new build.
+Runs the type-checks, the tests and the build locally, rsyncs `build/` to
+the droplet keeping the previous week's hashed assets, rsyncs the server and
+engine sources, installs dependencies, and restarts the duel server. A
+single-player game is in the player's own browser and loses nothing. A room
+is replayed from its ledger when the server comes back, which takes a few
+seconds; Caddy holds requests that land in the gap.
 
 ## Operations
 
-- Logs: `ssh root@<ip> journalctl -u caddy -f`, access log in
-  /var/lib/caddy/access.log
-- Nothing to back up on the server. Player duels are in their browsers.
+- Logs: `ssh root@<ip> journalctl -u waving-hands -f` for the duel server,
+  `journalctl -u caddy -f` and /var/lib/caddy/access.log for the web side.
+- Restart: `ssh root@<ip> systemctl restart waving-hands`
+- Rooms: `/var/lib/waving-hands/rooms/<CODE>.jsonl`, one ledger per duel.
+  Copy that directory to back them up; single-player games are in players'
+  browsers.

deploy/deploy.sh

@@ -1,10 +1,11 @@
 #!/usr/bin/env bash
-# Build locally and push the static site to the droplet.
-# Usage: deploy/deploy.sh <droplet-ip-or-host>
+# Build locally, push the static site and the duel server to the droplet,
+# and restart the server. Usage: deploy/deploy.sh <droplet-ip-or-host>
 set -euo pipefail
 HOST="${1:?usage: deploy.sh <droplet-ip-or-host>}"
 
 npm run check
+npm run check:server
 npm test
 npm run build
 
@@ -12,11 +13,27 @@ npm run build
 # fetch the module it was built against instead of failing mid-duel.
 rsync -az --delete --filter='P _app/immutable/*' \
   build/ "root@$HOST:/opt/waving-hands/build/"
+
+# The server runs from source with tsx; it needs the engine, its own code,
+# and the dependency manifest. Ledgers live outside this tree and survive.
+rsync -az --delete \
+  --include='/server/***' --include='/src/' --include='/src/lib/' --include='/src/lib/game/***' \
+  --include='/package.json' --include='/package-lock.json' --include='/deploy/' --include='/deploy/waving-hands.service' \
+  --exclude='*' \
+  ./ "root@$HOST:/opt/waving-hands/app/"
+
 ssh "root@$HOST" '
   find /opt/waving-hands/build/_app/immutable -type f -mtime +7 -delete
-  chown -R root:caddy /opt/waving-hands
-  chmod -R g+rX /opt/waving-hands
+  chown -R root:caddy /opt/waving-hands/build
+  chmod -R g+rX /opt/waving-hands/build
+  cd /opt/waving-hands/app && npm install --no-audit --no-fund --omit=optional
+  chown -R waving-hands:waving-hands /opt/waving-hands/app
+  cp /opt/waving-hands/app/deploy/waving-hands.service /etc/systemd/system/waving-hands.service
+  systemctl daemon-reload
+  systemctl enable --now waving-hands
+  systemctl restart waving-hands
   systemctl reload caddy
-  systemctl --no-pager -l status caddy | head -3
+  sleep 1
+  systemctl --no-pager -l status waving-hands | head -3
 '
 echo "deployed."

deploy/setup-server.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Adds the duel server to a droplet that setup-droplet.sh already prepared.
+# Run ON the droplet as root; safe to run again. Installs Node 22, creates
+# the service user and data directory, and teaches Caddy to hand /api and
+# /ws to the server while it keeps serving the static site itself.
+set -euo pipefail
+
+if ! command -v node >/dev/null || [[ "$(node -v)" != v22* ]]; then
+  curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
+  apt-get install -qy nodejs
+fi
+
+id -u waving-hands &>/dev/null || useradd -r -m -d /opt/waving-hands-home waving-hands
+mkdir -p /opt/waving-hands/app /var/lib/waving-hands/rooms
+chown -R waving-hands:waving-hands /var/lib/waving-hands
+
+# Caddy: the two proxied paths go in before the static file handling.
+if ! grep -q 'reverse_proxy' /etc/caddy/Caddyfile; then
+  python3 - <<'PY'
+import pathlib
+p = pathlib.Path('/etc/caddy/Caddyfile'); s = p.read_text()
+marker = 'try_files {path} {path}.html /index.html'
+proxy = '''@duel path /api/* /ws
+reverse_proxy @duel localhost:8788 {
+	lb_try_duration 30s
+	lb_try_interval 250ms
+}
+
+'''
+assert marker in s
+p.write_text(s.replace(marker, proxy + marker))
+PY
+  caddy validate --config /etc/caddy/Caddyfile
+  systemctl reload caddy
+fi
+
+echo "server prerequisites ready: now run deploy/deploy.sh <ip> from your machine"

deploy/waving-hands.service

@@ -0,0 +1,32 @@
+[Unit]
+Description=Waving Hands duel server
+After=network.target
+
+[Service]
+Type=simple
+User=waving-hands
+WorkingDirectory=/opt/waving-hands/app
+Environment=PORT=8788
+# Caddy terminates TLS; the plaintext port must not face the internet.
+Environment=HOST=127.0.0.1
+Environment=WH_DATA_DIR=/var/lib/waving-hands/rooms
+ExecStart=/opt/waving-hands/app/node_modules/.bin/tsx server/src/index.ts
+Restart=always
+RestartSec=3
+
+# Sandbox: the process reads /opt/waving-hands and writes only its data dir.
+NoNewPrivileges=yes
+PrivateTmp=yes
+ProtectSystem=strict
+ProtectHome=yes
+ReadWritePaths=/var/lib/waving-hands
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectControlGroups=yes
+RestrictSUIDSGID=yes
+# A runaway process gets killed and restarted before it can take the box down.
+MemoryMax=300M
+LimitNOFILE=4096
+
+[Install]
+WantedBy=multi-user.target