game-arcade — Build Recipe

Take a bare machine to a running copy of GameHub — a self-hosted family game arcade: a hub with username accounts, an avatar creator, a lobby with live chat / presence, and 11 games (8 in a shared multiplayer service plus standalone UNO, Boggle, and Pop the Lock). One Caddy reverse proxy fronts everything; each game lives on its own subdomain so it owns its origin. Node + Socket.IO + better-sqlite3, no build step for the clients.

Status: ✅ Verified 2026-08-01 — built from this clone with docker compose up -d --build (6 services) and driven end-to-end in a real browser: all 12 subdomains route (hub + 11 games), a new player + avatar is created from scratch, lobby chat + online presence work on first entry, a game launches across the subdomain boundary carrying the auth token, and two isolated browsers join the same blackjack table and see each other. Audio works out of the box (synthesized sound effects + a seeded background-music loop). Three bugs surfaced during verification and were fixed in the clone (see What was fixed). All three tiers are covered; the prebuilt tarball (docker save of caddy + the 5 game images) is ~1.0 GB, verified loadable 2026-08-01. The clean clone lives in clone/.

Sensitive data: none shipped. No family accounts, avatars, chat history, saved games, or music — the databases start empty and are seeded with three synthetic demo players. All hardcoded secrets (a shared INTERNAL_API_KEY, two JWT_SECRETs) were replaced with dev placeholders. Auth is username-only by design — a friendly home-arcade choice, not production security.

What it is

A set of small Node/Socket.IO servers behind one Caddy reverse proxy. There is no build, no ML, no dataset, and no GPU — "reproducing" it is just running the services. The only architectural trick is one origin per game: the hub is hub.arcade.localhost, blackjack is blackjack.arcade.localhost, and so on. The browser derives every URL from location.host, so the whole arcade rehosts under a different base domain by editing one file (Caddyfile) — no code changes.

Prerequisites

New machine? Install the base tools first — see ../SETUP.md. Then, per tier:

A modern browser resolves *.localhost to 127.0.0.1 automatically (Chrome, Edge, Firefox, Safari) — so http://hub.arcade.localhost/ just works with no hosts-file edits. That is the whole reason the demo uses arcade.localhost.

Configuration — nothing required

The arcade runs key-free. Every secret has a working dev default, so docker compose up needs no .env. To set your own, copy clone/.env.example to clone/.env:

JWT_SECRET=change_me            # signs the username-only session tokens
INTERNAL_API_KEY=change_me      # game↔game stats calls + the admin music manager

To host under your own domain (e.g. arcade.example.com): point a wildcard *.arcade.example.com at the box and change arcade.localhost → arcade.example.com in Caddyfile (12 lines). No app code changes — the client reads the base off location.host. For real internet exposure, switch the Caddyfile blocks from http:// to plain hostnames so Caddy provisions TLS automatically.

Tier 1 — Run the prebuilt containers (lowest friction)

Availability: the prebuilt image bundle is available on request — it is not published or linked anywhere. Ask Kevin for it, or build everything from source via Tier 2/3 below.

Build once, save the images to a tarball, and load them anywhere — no rebuild, no source needed:

# on a machine that has built the images (see Tier 2):
docker save caddy:2-alpine clone-game-hub clone-mini-games clone-uno clone-boggle clone-pop-lock \
  -o gamehub-images.tar          # ~1.0 GB (caddy is the pulled caddy:2-alpine; the 5 game
                                 #  images are locally built as clone-<service>)

# on the target machine:
docker load -i gamehub-images.tar
cd clone
docker compose up -d             # images already present → no build step
# → http://hub.arcade.localhost/

Tier 2 — Build from source (recommended; this is the verified path)

cd clone
docker compose up -d --build     # builds 5 Node images + pulls caddy, starts all 6 services
# → http://hub.arcade.localhost/

docker-compose.yml + the per-service Dockerfiles + Caddyfile are the build documentation — all clean, no LAN/host config. Only caddy publishes a host port (80); everything else talks over the internal bridge network by service name.

Tier 3 — Bare-metal (no Docker)

Run each service in its own terminal (or a process manager) and Caddy in front. From clone/:

# 1) game-hub
cd game-hub && npm install && DB_PATH=./data/gamehub.db PORT=3003 node server.js

# 2) the 8-in-1 mini-games service (uses pm2)
cd mini-games && npm install && npx pm2-runtime ecosystem.config.js     # serves :3001–3009

# 3) the three standalone games
cd uno      && npm install && PORT=3010 node server.js
cd boggle   && npm install && PORT=3011 node server.js
cd pop-lock && npm install && PORT=3011 node server.js   # (use a different port if 3011 is taken)

# 4) Caddy out front — the Caddyfile already maps every subdomain to a service:port.
#    Bare-metal has no Docker DNS, so point the upstreams at 127.0.0.1 first:
sed 's/game-hub:3003/127.0.0.1:3003/; s/mini-games:/127.0.0.1:/; s/uno:/127.0.0.1:/; \
     s/boggle:/127.0.0.1:/; s/pop-lock:/127.0.0.1:/' Caddyfile > Caddyfile.local
caddy run --config Caddyfile.local --adapter caddyfile

Give boggle and pop-lock distinct ports here (both default to 3011 — fine as separate containers, but they collide on one host); update the two ports in Caddyfile.local to match.

Verify

# every subdomain answers through Caddy (Host header bypasses DNS):
for h in hub blackjack tetris snake bomber cardclash tower bubble blockgame uno boggle poplock; do
  printf "%-12s %s\n" "$h" "$(curl -s -o /dev/null -w '%{http_code}' -H "Host: $h.arcade.localhost" http://127.0.0.1/)"
done
# → all 200

Then in a browser at http://hub.arcade.localhost/: 1. Click New Player → Quick, hit 🎲 Randomize, type a callsign, CREATE → you land in the lobby. 2. Type in lobby chat and Send → your message appears; the online counter shows you. 3. Click ▶ Play Now on Royal 21 → you're on blackjack.arcade.localhost with your name pre-filled (the token rode across on the URL). Create Table → note the table code. 4. In a second browser / private window, join as a different player with that code → both windows show both players at the table. (That's the multiplayer path.) 5. Click the 🔊 toggle to cycle off → sfx → all; on all you get the background-music loop.

Notes & gotchas

• *.arcade.localhost needs no hosts file — modern browsers special-case .localhost to loopback. Command-line tools (curl, node) do not, which is why the CLI checks above use a Host: header.
• One origin per game, not one port per game. The original addressed games by host:port; a port is part of the origin, so that already crossed origins. The clone swaps ports for subdomains — same origin-crossing, but every game now owns its own root path, so zero in-game code changed to rehost.
• The auth token crosses origins via the URL. localStorage is per-origin, so the hub can't share its token with a game subdomain — the hub appends ?user=&token= when it launches a game, and the game reads it there. This is by design (it matched the original port-based behavior).
• Username-only auth. Anyone can log in as any name; tokens are signed but there's no password. It's a home arcade, not a hardened service — don't expose it to the open internet as-is.
• Audio: all sound effects are synthesized in the browser (Web Audio oscillators) — no files. Background music loads from /audio/music.mp3; the clone seeds a short, self-authored, royalty-free ambient loop on first boot (game-hub/scripts/make_default_music.py), and admins can replace it through the in-lobby 🎵 music manager (which is gated by INTERNAL_API_KEY).
• Client assets are cached for a day (express.static(..., { maxAge: '1d' })). If you edit client JS/HTML and don't see the change, hard-refresh (or bump the cache).
• Empty tables rotate. A blackjack table with no second player is recycled after its idle countdown, so share the code and join promptly.

What was fixed (bugs surfaced during verification)

• All four SQLite services crash-looped (SQLITE_CANTOPEN). Each Dockerfile declared VOLUME ["/app/data"] before chown; Docker discards build changes to a volume path, so the data dir stayed root-owned and the non-root runtime user couldn't open its .db. → create + chown /app/data before the VOLUME line.
• Chat and presence were dead for a freshly-created player. connectSocket() (which registers the chat/presence handlers) was only called on the page-reload auto-login path, never from enterLobby(). → call it from enterLobby(), made idempotent.
• Multiplayer was broken — table codes churned and joins failed. The blackjack server called broadcastQuip(...) in its join handler, but the function was undefined → it crashed on every join; pm2 restarted it and the in-memory tables vanished. → defined broadcastQuip using the file's own quip idiom.

What was stripped / changed from the family version (recipe minimalism)

• The real LAN addressing — games hardcoded the home server's LAN hostname (http://<home-server>:<port>) — → subdomain-per-game behind one Caddy (*.arcade.localhost), derived from location.host.
• Family data — real accounts, avatars, chat history, and saved games → databases start empty; three synthetic demo players (demo_ace, demo_nova, demo_pixel) are seeded on boot.
• The external avatar service — the original proxied a private avatar generator (and named DiceBear styles) → a self-contained, deterministic geometric identicon generator (no network).
• Hardcoded secrets — a shared INTERNAL_API_KEY and two JWT_SECRETs → dev placeholders that all services share via Compose defaults.
• Google Fonts (CDN <link>/@import) → system font stacks (fully offline).
• Real music tracks → one self-authored royalty-free default loop, seeded on boot.
• Two never-shipped games (brainrot, fortnite_2d) trimmed from the launch/validation lists.

Provenance (no data, no model, no GPU)

Nothing is trained and nothing is downloaded at runtime. Avatars are generated locally (a hashed 5×5 symmetric identicon); the background-music loop is synthesized by the included Python script. No datasets, no weights, no external services.