Deploying the game server
The central game server is the one piece of horrible-dashboard that runs as a hosted, always-on service rather than on each user's node. This page covers where to host it, the constraints that drive that choice, and the config it needs. The chosen path is Fly.io; the options comparison documents the alternatives for when that changes.
What the server needs from a host
Three properties of backend/games_server/ decide which hosts fit:
- Stateful, single-process. The
GameHubholds the lobby of tables, liveRefereeinstances, and the account→connection map in process memory. A second replica wouldn't see the first's tables, so it must run as one instance — no autoscaling, no multi-replica load balancing (yet). - Long-lived WebSockets. Nodes hold a persistent
/game-wsconnection. The host must support WebSockets, allow long idle periods (a turn clock can sit ~30s between moves), and never scale to zero — a cold start drops every live match. - Persistent disk. State lives in SQLite at
$HORRIBLE_DATA_DIR/game_server.db(accounts, ELO ratings + placements/tiers, results, series, replays, challenge scores, the code-game task bank) plus a generated JWT-secret file. It needs a persistent volume, not an ephemeral container filesystem. The schema evolves through an ordered, additive-onlystore.MIGRATIONSlist replayed on boot — see schema migrations & backups.
This rules out serverless/edge functions (no long-lived WS server), anything that scales to zero, and multi-replica-behind-a-load-balancer — for now. See scaling path for how those unlock later.
Configuration & secrets
Set via the host's env/secret mechanism (all read by backend/games_server/auth.py
and store.py). Environment variables take priority over database settings if both are
present — except the client secrets, which have no settings fallback at all (see
the note below).
| Variable | Required | Purpose |
|---|---|---|
GAMES_JWT_SECRET | Yes in prod | HMAC key that signs session JWTs. If unset the server writes a random secret into HORRIBLE_DATA_DIR — on an ephemeral FS that regenerates on every restart and logs everyone out. Set it explicitly (openssl rand -hex 32). |
GAMES_GITHUB_CLIENT_ID | For sign-in | GitHub OAuth app client id. Without it, "Sign in with GitHub" returns a friendly "not configured" error and only the dev token works. Overrides the database games.github.clientId setting. |
GAMES_GITHUB_CLIENT_SECRET | For the redirect flow | GitHub OAuth app client secret, required by the default redirect (authorization-code) sign-in for the code→token exchange. Also register https://<server>/auth/github/callback as the app's Authorization callback URL. The device-flow fallback (use a code) needs neither. Env/secret only — no settings fallback. |
GAMES_GOOGLE_CLIENT_ID | For Google sign-in | Google device-flow client id — client type "TVs and Limited Input devices" (add your accounts as test users while the consent screen is in Testing). This client type has no redirect URI, so it is used by the device flow only. Overrides the database games.google.clientId setting. |
GAMES_GOOGLE_CLIENT_SECRET | For Google sign-in | The matching device-client secret — Google's device token poll requires it. Env/secret only — no settings fallback. |
GAMES_GOOGLE_WEB_CLIENT_ID | For Google redirect sign-in | A second, separate OAuth client of type "Web application", with https://<server>/auth/google/callback registered as an authorized redirect URI. Reusing the device client here is what produces Error 400: redirect_uri_mismatch — it cannot carry a callback. Unset, the server reports Google's web flow unavailable and clients fall back to the device flow. |
GAMES_GOOGLE_WEB_CLIENT_SECRET | With the above | The web client's secret, for the code→token exchange. Env/secret only — no settings fallback. |
GAMES_PUBLIC_URL | Optional | The externally-reachable base URL (e.g. https://games.example.com) used to build the OAuth redirect_uri. Only needed if the server can't infer it from the request — behind a TLS-terminating proxy the inbound scheme can read as http; off localhost the server already coerces to https, so this is a belt-and-suspenders override. |
GAMES_ALLOW_DEV_AUTH | Recommended 0 | The dev token treats token == account_id (no auth). Fine locally; set to 0 in prod to require real sign-in. |
GAMES_ENABLE_CODE_EXEC | For code games | Opt-in gate for running untrusted code — the verification runner (code golf, test duel, bug hunt) and the arena bot simulation. Unset, those games report grading as unavailable and never execute anything. Only enable on a host you're comfortable running player-submitted Python on (isolated subprocess, but not container-grade yet — see the architecture note). |
GAMES_QUEUE_BOT_S | Optional (default 45) | Seconds the ranked queue waits for a human before backfilling with a practice bot (instant for placement matches). |
HORRIBLE_DATA_DIR | Yes | Where the SQLite db + JWT secret live. Point at the mounted persistent volume. |
GAMES_WEB_ORIGINS | For the web client | Comma-separated browser origins allowed to call the server's HTTP routes (CORS, GET only, no credentials), e.g. https://play.example.com. Empty by default — nodes are not browsers and need none. See the standalone web client. |
GAMES_WEB_ORIGIN_REGEX | Optional | A regex of extra allowed origins, for hosts that mint a URL per deploy (preview deployments). |
HASSAULT_MAX_ROOMS | Optional (default 12) | Most hassault rooms the server runs at once. Guests need no account, so this is what bounds how much simulation strangers can start. Only opening a room is refused; joining one that exists never is. |
Secrets are env-only
The client ids above fall back to a database setting (games.github.clientId,
games.google.clientId, games.google.webClientId) — an id is public by design. The
three client secrets deliberately do not: they are read from the environment and
nowhere else.
GET /api/settings returns the whole settings bag to the browser, unfiltered. When the
game server runs bundled alongside a node (pnpm dev, the desktop shell) the two share
$HORRIBLE_DATA_DIR/settings.json, so a secret stored as a setting there would be
readable by any page the node serves. Set them with fly secrets set (or your host's
equivalent); an unset secret degrades gracefully — /auth/providers reports that flow
unavailable and clients fall back to the device flow or the dev token.
Nodes connect by setting the games.serverUrl setting to your server's wss://
URL (e.g. wss://games.example.com); terminate TLS at the host/proxy.
Run it without --reload:
uv run uvicorn backend.games_server.app:app --host 0.0.0.0 --port 9200
Fly.io (the chosen path)
A single Fly Machine with a small volume fits all three constraints: native
WebSockets, automatic TLS + subdomain, a persistent volume for SQLite, and you pin it
to one always-on instance. The config is fly.toml at the repo root, and it points
at the image via [build] dockerfile = "deploy/game-server/Dockerfile". fly.toml
lives at the root deliberately: flyctl resolves the build context (and the Dockerfile
path) relative to the config file's directory, and the image needs repo-root files
(pyproject.toml, uv.lock, backend/) — a fly.toml in a subdirectory doubles the
Dockerfile path and breaks the COPY context.
# From the repo root. One-time:
fly launch --no-deploy --copy-config # uses ./fly.toml
fly volumes create game_data --size 1 --region iad
fly secrets set GAMES_JWT_SECRET="$(openssl rand -hex 32)" \
GAMES_GITHUB_CLIENT_ID=<your-oauth-client-id> \
GAMES_GITHUB_CLIENT_SECRET=<your-github-client-secret> \
GAMES_GOOGLE_CLIENT_ID=<your-google-device-client-id> \
GAMES_GOOGLE_CLIENT_SECRET=<your-google-device-client-secret> \
GAMES_GOOGLE_WEB_CLIENT_ID=<your-google-web-client-id> \
GAMES_GOOGLE_WEB_CLIENT_SECRET=<your-google-web-client-secret>
# For the default redirect sign-in, register the callback on each OAuth app:
# GitHub app → Authorization callback URL: https://<server>/auth/github/callback
# Google → a SECOND client of type "Web application" (the device client cannot
# hold a redirect URI), Authorized redirect URI:
# https://<server>/auth/google/callback
# Deploy / redeploy (builds the web client and the native client download first —
# the image COPYs both):
pnpm deploy:games
On Windows PowerShell (no openssl), generate the secret with .NET's CSPRNG instead:
fly secrets set GAMES_JWT_SECRET=([Convert]::ToHexString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))).
The fly.toml pins the important bits: internal_port = 9200, force_https,
auto_stop_machines = 'off', min/max_machines_running = 1 (single authority), a
/health check, and a game_data volume mounted at /data. Secrets are set with
fly secrets — never committed. Cost is roughly a shared-cpu-1x/512 MB machine plus
a 1 GB volume. The one-volume "create two or more" warning from fly volumes is
expected here — a single instance wants a single volume; HA comes later via the
scaling path, not a second volume.
Schema migrations & backups
store.py owns the schema through an ordered, additive-only MIGRATIONS list
tracked in a schema_meta.version row; init_db() (run at startup) replays any
migrations past the DB's current version, each in its own transaction. New columns
are added with a defaulted ALTER TABLE, new tables with CREATE TABLE IF NOT EXISTS — never a destructive change — so deploying a newer server upgrades the
live volume in place. A migration may also backfill data (e.g. _m6 derives a
locked handle from each pre-existing account's OAuth username, oldest-first with
numeric-suffix collision resolution, skipping bots). Nodes feature-detect what the
server supports via the caps list on authed, so a server can always deploy ahead
of node releases.
Because a migration edits the live SQLite file, back it up before a deploy that bumps the schema version:
fly ssh console -C "sqlite3 /data/game_server.db \".backup '/data/backup.db'\""
# then optionally pull it down:
fly ssh sftp get /data/backup.db ./game_server.backup.db
To generate fresh bug-hunt tasks (the mutation generator), run it against the volume with the exec gate on — offline or on a cron, not in the request path:
fly ssh console -C "GAMES_ENABLE_CODE_EXEC=1 uv run python -m backend.games_server.task_gen --count 20"
Hosting options
All of these satisfy the "single always-on instance + WebSockets + persistent disk" shape. Pick on ops appetite and budget.
| Option | Best when | Notes |
|---|---|---|
| Fly.io (chosen) | You want managed TLS + a subdomain and minimal ops, from a Dockerfile. | Pin to one Machine + a volume. WS supported natively. deploy/game-server/ is ready to go. |
| Plain VPS + Caddy (Hetzner ~€4/mo, DigitalOcean $6) | Cheapest, simplest mental model; you're comfortable with a Linux box. | uv run uvicorn … under a systemd unit, behind Caddy for automatic HTTPS + WS pass-through (a ~5-line Caddyfile). SQLite on the box's disk. Most control, most (light) ops. |
| Render / Railway | You want click-to-deploy PaaS. | Create a web service with a persistent disk attached; turn scale-to-zero OFF and keep it a single instance. Slightly pricier; disk semantics vary by plan. |
| Bare container host (ECS/Cloud Run/K8s) | You already run container infra. | Works, but overkill for one stateful process — and Cloud Run's scale-to-zero/request model fights the long-lived WS. Use only if it's where your ops already live, pinned to one always-on task with a volume. |
Avoid for now: Vercel/Netlify functions and other serverless/edge (no persistent WS server), anything that scales to zero, and multi-replica behind a load balancer (splits the in-memory game state). A static host is fine for the web client's files — it is the server that cannot live there. See below.
The standalone web client
apps/assault-web is HorribleAssault in a browser with no node behind it: a
guest picks a callsign and plays on this server. This server hosts it: the
image copies apps/assault-web/dist in and _mount_web_client serves it at /,
so https://horrible-games.fly.dev/ is the game. Same origin means no
VITE_BACKEND_URL and no CORS entry. The build happens on the host (it needs the
whole pnpm workspace), which is why the deploy command is pnpm deploy:games — a
bare fly deploy with no build fails on the COPY instead of shipping without a
site. It is still a plain static build, so a CDN (with VITE_BACKEND_URL and
GAMES_WEB_ORIGINS set) remains an option if the ~60 MB of models ever outgrows
one machine's bandwidth.
That makes this server the client's entire backend, which it was not built to
be. In dev it looked as if it were, because Vite proxied /api to a node and only
/hassault-ws here — a deployed build 404ed on its first map fetch. So the server
now carries:
- The read-only half of
/api/hassault(hassault_content.py): maps, map info, cube planes, meshes, modes, weapons, items, grenades, throw constants, hitbox, lore, textures. These are the node's own handler functions registered on a second router, not copies — the client predicts against these numbers and the server simulates with them. Bundled maps only (no install maps, nodraft:documents) andGETonly: hitbox tuning, drafts, the console and the armoury stay on nodes, where "the account" means something. - CORS, closed unless
GAMES_WEB_ORIGINSnames the site. Without it a browserfetchfails before reaching a route while the websocket connects fine, which looks like a broken map loader rather than a config gap. - A room cap (
HASSAULT_MAX_ROOMS), and no replay recording on server rooms — a recorder held every tick in memory for the room's life, which on an always-on public room is an out-of-memory crash on a timer. - On
/hassault-ws: the welcome is the room's wholestate_payload(items, what is taken, mode, scores — it used to be five fields, so pickups never drew),pingis answered (the HUD's RTT), and a share link to a room that has since closed lands on that map instead of failing.
The client side of the same contract is the panel's standalone prop: it skips
everything that means "this node" (account, armoury, friends, native launcher,
the debrief poll) and joins a match on load. See
hassault.
The native client download
The server also hands out the native client as a file:
https://horrible-games.fly.dev/download/hAssault.exe. Downloaded and
double-clicked, it plays on this server as a guest with no dashboard node involved
(what standalone means for the client).
The landing page links it from the hero.
| Route | Answers |
|---|---|
GET /download/hAssault.exe | The Windows build, as an attachment. Range and If-Range resume an interrupted download; If-None-Match is a 304; X-Checksum-Sha256 carries the checksum |
GET /download/info | {"windows": {url, version, commit, sizeBytes, sha256, builtAt}}, or {"windows": null} when this deploy carries no build |
It is hosted here, and not only on the GitHub release a node installs from, because the client and the server are two halves of one wire. A release asset is keyed by a tag; this server is deployed from a checkout, usually ahead of the last tag. The executable offered here is built by the same command, from the same checkout, as the server that will simulate it.
Built on the host, like the web client. pnpm deploy:games runs
pnpm build:hassault:download (scripts/stage-hassault-download.mjs), which builds
the release client and writes it into apps/native-fps/dist/ with a manifest.json;
the image copies that directory in. The builder is Linux and cannot produce a Windows
executable, and the machine deploying already can. To stage without rebuilding:
pnpm build:hassault:download -- --no-build
Three behaviours worth knowing before they surprise you:
- A deploy from Linux or macOS ships no download, and does not fail. The staging
script writes a manifest with
windows: nulland says so loudly./download/infothen answersnulland the landing page shows no button. Deploy from Windows to ship one. - The checksum is the staging script's claim, not the server's. Nothing re-hashes 130 MB per request. The server only repeats the checksum while the file on disk is still the size the manifest recorded; a file swapped underneath it is served with no checksum rather than with one describing something else.
FileResponsedoes not answerIf-None-Match(onlyStaticFilesdoes), so the route does it itself against the ETagFileResponsecomputed. Without that, a revalidation is the whole file again.
What it costs: the executable is about 130 MB (every model, texture and map mesh is compiled in, which is why it needs nothing else), so the image and each deploy's upload grow by that much, and every download is that much egress.
Windows SmartScreen stops an unsigned executable from the internet the first time: More info, then Run anyway. The landing page's link says so in its tooltip. The fix is a code-signing certificate, not anything in this repo.
A deploy replaces the file on the server, not the copy on somebody's disk. An older
client keeps working for as long as the wire it speaks does, and reports what it does
not understand (divergence.rs) rather than refusing to play. There is no version
check at startup yet.
Scaling path
None of this is needed for turn-based, play-money games at launch — one small box serves a lot — but when it matters:
- Durability / backups:
backend/games_server/store.pyis the only DB layer. Swap SQLite → managed Postgres (the schema is a handful of simple tables: accounts, ratings, results, challenge_scores). - Horizontal scale: only once you need >1 instance, move the hub's live table/seat state out of process memory (e.g. Redis) with sticky routing per table, so the authority can span machines. Until then, single-instance is a feature (one referee, one source of truth), not a limitation.
See game server architecture for the referee, anti-cheat, and
identity design, and setup for the local pnpm dev workflow (which
runs a game server on :9200 for you).