Deploying (single node, Docker, behind a proxy)
In v1 a Shoehive server is one Node.js process (Node 22 or newer) that holds every live table in memory and writes each action to a store. This page takes that process to production: configuration, a durable store, shutdown, a proxy, Docker and health checks.
Production mode
Section titled “Production mode”Set NODE_ENV=production. It turns off the development checks in table runtimes (frozen
state and the nondeterminism guard), ignores devtools: true, and makes the server strict
about secrets.
Resume tokens are signed with a secret. Set it in the environment as SHOEHIVE_SECRET (or
pass secret). Without one the server throws on startup in production, unless you supply an
auth hook, and it would otherwise invent a random secret that changes on every restart.
export NODE_ENV=productionexport SHOEHIVE_SECRET="$(openssl rand -hex 32)"To rotate it, pass an array to secret: the first signs new tokens and all of them verify old
ones. Guest identities are bearer tokens and are not suitable for real money, so use an
auth hook when you run a wallet. See
authentication.
Pick a store
Section titled “Pick a store”The default store keeps everything in memory, so a restart ends every table. Choose a durable
one before you go live: sqliteStore for one server with a disk, postgresStore or
redisStore if you already run them. The adapters, their durability settings and their
tables are on the stores reference, and
persistence and restart recovery explains what
players see after a restart.
The server
Section titled “The server”You can let Shoehive own the HTTP server with await shoehive.listen({ port, host }), or
attach the WebSocket endpoint to one you already have, which is what most apps do (the
examples serve their web app this
way). listen binds to 127.0.0.1 unless you pass host: '0.0.0.0', which a container
needs, and it answers every plain HTTP request with 426, so use attach when a load
balancer needs an HTTP health check.
const port = Number(process.env.PORT ?? 3000);const store = sqliteStore({ file: process.env.DB_FILE ?? './shoehive.db' });
// SHOEHIVE_SECRET is read from the environment. With NODE_ENV=production the server// refuses to start without it (or without an `auth` hook).const shoehive = createServer({ games: [ticTacToe], store, // Only pages served from these origins may open a WebSocket. Empty means any origin. origins: process.env.ORIGINS?.split(',') ?? [],});
let ready = false;void shoehive.ready.then(() => { ready = true;});
// Your own HTTP server: the health check lives here, next to the WebSocket endpoint.const http = createHttpServer((req, res) => { if (req.url === '/healthz') { res .writeHead(ready ? 200 : 503, { 'content-type': 'text/plain' }) .end(ready ? 'ok' : 'starting'); return; } res.writeHead(404).end();});await shoehive.attach(http);http.listen(port, '0.0.0.0');GET /healthz answers 503 until stored tables have been recovered (shoehive.ready) and
200 after, so a rolling deploy only sends traffic to a process that is ready.
Shut down gracefully
Section titled “Shut down gracefully”When the platform stops the process it sends SIGTERM. Call shoehive.close(): it waits for
each table's queue to drain, writes a final snapshot, and closes connections with code 1001,
which clients treat as a reason to reconnect with backoff and resume. Then close your HTTP
server and the store, because close() leaves a store you created open.
async function shutdown(): Promise<void> { await shoehive.close(); // snapshots every table, then closes sockets with code 1001 await new Promise((resolve) => http.close(resolve)); await store.close(); // the server does not close a store you created process.exit(0);}process.once('SIGTERM', () => void shutdown());process.once('SIGINT', () => void shutdown());close({ graceful: false }) drops everything at once, like a crash. It is useful in a test
of your recovery, not in a deploy.
Behind a reverse proxy
Section titled “Behind a reverse proxy”The proxy must pass the WebSocket upgrade through. For nginx:
location /shoehive { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_read_timeout 1h;}Raise the proxy's idle timeout above its default (60 seconds in nginx). The server pings every
15 seconds (limits.heartbeatMs), which keeps a healthy connection busy, but a long timeout
stops the proxy cutting a quiet one. A cloud load balancer needs the same: WebSocket support
on, and an idle timeout of a minute or more.
Set origins to the sites that host your client, for example
['https://play.example.com']. A browser upgrade from any other origin is refused with
HTTP 403. Without it, guest servers accept any origin, and servers with an auth hook accept
only same-origin pages in production. Behind a proxy, make sure the Host header reaches the
server unchanged (or list origins). The socket path is /shoehive unless you pass path.
Docker
Section titled “Docker”FROM node:22-slim AS buildWORKDIR /appCOPY package*.json ./RUN npm ciCOPY . .RUN npm run build
FROM node:22-slimENV NODE_ENV=production \ DB_FILE=/data/shoehive.dbWORKDIR /appCOPY package*.json ./RUN npm ci --omit=devCOPY --from=build /app/dist ./distRUN mkdir /data && chown node:node /dataVOLUME /dataUSER nodeEXPOSE 3000HEALTHCHECK --interval=30s --timeout=3s \ CMD node -e "fetch('http://127.0.0.1:3000/healthz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"CMD ["node", "dist/server.js"]Run it with the secret from outside the image, and keep the volume so tables survive a redeploy:
docker run -p 3000:3000 -v shoehive-data:/data \ -e SHOEHIVE_SECRET -e ORIGINS=https://play.example.com my-gameRun the container directly as the main process, as above, so SIGTERM reaches Node. With
Postgres or Redis there is no volume to keep, and you end the pool or client in shutdown.
Scaling
Section titled “Scaling”v1 targets a single node. Players, tables and timers live in that process, so you scale it up
(more CPU and memory), not out. Do not run two server processes against the same store
namespace: the second writer gets a StoreConflictError and the table is faulted until you
reload it. A restart is a short pause, not data loss: with a durable store the next process
recovers every open table and players resume. See the
benchmarks for what one process handles.
Devtools stays off in production. If you must use it for a short session, follow the devtools reference.
