Skip to content

t1k:gamebackend:game-server:template-bootstrap

FieldValue
Modulegame-server
Version1.10.3
Effortmedium
Tools—

Keywords: game server template bootstrap, gameservertemplate repo, instantiate game server template, new game backend worker, separate server repo, server folder in game repo, server in the game repo, where does the server live

/t1k:gamebackend:game-server:template-bootstrap
<game name> <api domain>

Bootstrap a game backend from GameServerTemplate

Section titled “Bootstrap a game backend from GameServerTemplate”

Instantiate the studio template repo The1Studio/GameServerTemplate (private) into a new game’s backend at server/ inside the game repo (the default layout; decision and its one exception in t1k-gamebackend-game-server-architecture § Decision), then rename, provision and deploy it with the cf CLI only. wrangler is retired studio-wide and denied by a hook; a missing cf command is a gap to report, never a reason to fall back (core t1k-cloudflare, its gaps-and-no-fallback reference file). Architecture and invariants: t1k-gamebackend-game-server-architecture. Contract port: t1k-gamebackend-game-server-rest-contract-port.

Status. The1Studio/GameServerTemplate is a real private repo, default branch main (read 2026-10-09 with git ls-remote / gh api). main carries the section runtime (src/core/runtime/), the identity context, the red-proofs runner and, since PR #3 (5c6b4d6), the SteelBorn hardening (atomic rate limiter + migration 0002, If-Match 400, zero-amount no-op, JWT header guard). It has no CI workflow and no branch protection: run bun test (--maxWorkers) yourself before trusting a ref. Its root holds setup.sh, cloudflare.config.ts, src/, test/, migrations/, scripts/, types/, vite.config.mts, .env.example, CONTRIBUTING.md, CHANGELOG.md. Prefer setup.sh (slug, domain, DO-class rename) over the manual table below; read the template’s README and its CHANGELOG.md “Unreleased” first and trust them over this list. Seam check, runtime guards, setup.sh failure handling, and the monorepo pull flow (the template itself ships no pin files; the .template-pin.json / core-files.sha256 / sync-template.sh / verify-core-pin.mjs flow is what a game repo adds — a server that IS its own repo root pulls core with git checkout template/main -- src/core per the template’s CONTRIBUTING.md): references/core-guards-and-pull-flow.md.

IntentGo to
“Where does the server live?”Place it
“Do I have what I need?”Preconditions
“Rename everything for my game”Rename
“Create D1, set secrets, deploy”Provision and deploy
“What can I never change after deploy?”Irreversible
“Seam check, runtime guards, setup.sh failure, pull core into a monorepo”references/core-guards-and-pull-flow.md
“First production deploy: one deployer, secrets proof, migration order, urgent review routing”references/deploy-and-ops.md
“Can a handler reach env/secrets? A static guard (check-grants) that passes too easily”references/static-guards.md

The server goes in the game repo, at server/, and the game’s .gitmodules, CI and docs all point into it. Copy the template’s tree there rather than creating a repo for it:

  1. Vendor the template into server/. Add the template as a remote on the GAME repo (git remote add template git@github.com:The1Studio/GameServerTemplate.git), then read the template’s tree into the subdirectory — git fetch template first, and git read-tree --prefix=server/ -u template/main (or a git archive template/main | tar -x -C server/ when the working tree is busy). setup.sh stages work too: it edits files relative to its own directory, so run it from inside server/ (cd server && ./setup.sh --yes --slug <game> --domain <game>-api.the1studio.org), never from the repo root with a path argument.
  2. One core pin per server. A server/ subdirectory is the monorepo case in references/core-guards-and-pull-flow.md § “Pull flow inside a monorepo subdirectory”: git checkout template/main -- src/core does NOT resolve from the game-repo root, so ship .template-pin.json + core-files.sha256 + scripts/sync-template.sh at server/ and let server/’s own bun test run verify-core-pin.mjs.
  3. Ignore the server’s build output from the GAME root. The repo root .gitignore needs the server’s node_modules/, dist/, .cf/, .dev.vars, .wrangler/; the template’s own .gitignore covers them only if something reads it, and a root-level client build does not. Check with git status --porcelain server/ after a bun install --frozen-lockfile + bun test: it must be empty but for files you intended.
  4. Root docs name the subdirectory. The game’s AGENTS.md/CLAUDE.md says the server is server/ (Hono + Zod + TypeScript on Workers, cf deploys, GOP source of truth for its own commands) and points at server/AGENTS.md for the rest, so an agent working on the Unity project does not go hunting for a separate server repo.
  5. One CI lane per tree. The server’s tests run from server/ (bun test, --maxWorkers=4); the client’s build does not. A server change and a client change in one PR still run both, which is the point of the same repo.

Access to The1Studio/GameServerTemplate is required. No new repo is created in the default shape; that is the whole decision above. Only the shared-backend exception creates one, and it is private and owner-approved.

  • Node.js 22.18.0 or newer (the cf config loader needs module.registerHooks).
  • cf pinned as a devDependency (the studio pin is in core t1k-cloudflare, its beta-caveats-and-fallback reference file); cf auth whoami works, or CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID are set (the env token wins over a stored profile).
  • A brand domain for the API, declared in cloudflare.config.ts from the first deploy. Never *.workers.dev or preview URLs (workersDev: false, previewUrls: false).
  • Access to The1Studio/GameServerTemplate, and write access to the game repo (the server ships in it, per Place it).

Change these together, in one commit, before the first deploy:

WhatWhereNote
Worker namecloudflare.config.ts worker.name, package.json nameone Worker per game and environment
API hostcloudflare.config.ts worker.domainsbrand domain, e.g. <game>-api.the1studio.org
D1 directory namebindings.d1({ name }) and the cf d1 create belowresource commands take ids, not names
APP_SERVER_ID (optional) text bindingbindings.text(...) in config, or leave it outper-deployment server id; absent means 1, a malformed value is refused by name. Not in the template’s config (the template declares only DIRECTORY, JWT_SIGNING_KEY, APP_SECRET_KEY, TOKEN_ISSUER, TOKEN_AUDIENCE) — add it only when two deployments must not share id 1. TOKEN_ISSUER / TOKEN_AUDIENCE are derived from the worker name setup.sh already writes
compatibilityDatecloudflare.config.tsdo not exceed what the pinned cf/workerd accepts (the spike’s pinned binary rejected a newer date)
Do NOT rename the Durable Object class key (PlayerDO)worker.exportssee below

All write commands accept --dry-run; run it first and read the method, URL and body.

  1. D1 directory. cf d1 create --name <game>-directory, note the id. Apply migrations: cf d1 migrations apply <database> (--dir, --pattern, --table exist; list pending with cf d1 migrations list <database>; create one with cf d1 migrations create <message>). There is no cf d1 import and no --file: send SQL through cf d1 query <database-id> --sql "..." or report the gap.
  2. Secrets — first deploy uses the secrets FILE. The template’s README and the setup.sh next-steps both make the first deploy seed the secrets from a file: umask 077; SECRETS=$(mktemp); printf 'JWT_SIGNING_KEY=%s\nAPP_SECRET_KEY=%s\n' "$(bun scripts/gen-jwt-key.mjs)" "$(openssl rand -hex 32)" > "$SECRETS"; cf deploy --secrets-file "$SECRETS"; rm -f "$SECRETS". cf workers secrets bulk needs an existing Worker, so it is for later rotation/adds, not the first deploy (SteelBorn first-deploy note, core #4113). For those later changes write a JSON merge-patch file with mode 0600 in a temp dir, for example {"JWT_SIGNING_KEY":{"type":"secret_text","text":"<jwk json>"},"APP_SECRET_KEY":{"type":"secret_text","text":"<value>"}}, then cf workers secrets bulk --worker <name> --body @<file> --dry-run with a placeholder body first, then the real call, then delete the file. --text <value> puts the secret on argv (visible in ps and history): throwaway values only. cf cannot set a single secret yet. Unlisted secrets are untouched; null deletes one.
  3. Local run. Copy .env.example to .dev.vars (git-ignored) and fill it; cf dev. Production values are Worker secrets and never enter git.
  4. Dry run. cf deploy --dry-run. It proves build and config resolve. It does not surface bindings.secret() values, so it does not prove the secrets exist in the target account.
  5. Deploy. cf deploy (beta: output and config can change). A pure API Worker still needs exactly one declared Cloudflare dev-server plugin (SteelBorn: @cloudflare/vite-plugin plus vite.config.mts), else cf deploy --dry-run exits early with “No Cloudflare dev-server is installed in this project.”
  6. Smoke the brand domain: GET /health (unauthenticated liveness), POST /connect/token for a guest, a route with no token answers 401, an unknown path answers the contract’s 404 envelope. First deploy and first secrets are the same command (cf deploy --secrets-file, step 2), so there is no “secrets before the Worker exists” ordering problem — cf workers secrets bulk is for later only. Whether the --secrets-file format works end to end against a real account is UNVERIFIED — the template’s README says the format was not exercised end to end against a real account while it was built (cf is beta): confirm on your first deploy.
  7. Tests before every deploy: bun test with a worker cap (--maxWorkers=4; the workstation is shared, never two full suites at once).

A key in worker.exports is a Durable Object namespace. exports.durableObject({ state: "deleted" | "renamed" | "transferred" }) drives lifecycle operations that a Worker rollback cannot undo, and deleting a class permanently removes its data. There is no migrations array in cf config; cf migrate does not convert wrangler DO migrations to worker.exports, and a wrong declaration on the first switch can delete a class. Treat the block as append-only: evolve behaviour by changing the class code, never its key.

No live log tail (cf logs query / cf observability telemetry query semantics UNVERIFIED), no single-secret set, no cf d1 import. File them with /t1k:issue (background) on the owning repo, with the anonymous task and cf --version. Per-environment config uses --mode staging / --mode production with separate Worker names and resources; its behaviour against a Durable Object Worker is UNVERIFIED until run once for real.

Gaps hit on SteelBorn (reported by the server author)

Section titled “Gaps hit on SteelBorn (reported by the server author)”

Three cf gaps were hit and filed in core. Their state was read with gh issue view <n> -R The1Studio/theonekit-core --json state on 2026-10-08: all three are CLOSED. Which cf version carries each fix, and whether it matches the behaviour below, is UNVERIFIED; re-check with your pinned cf before relying on a workaround.

ObservedCore issue (title as filed)
cf deploy needs a dev-server plugin (@cloudflare/vite-plugin) even for an API-only Worker#4114 (vite + plugin, --mode deployments)
first deploy cannot use workers secrets bulk before the Worker exists#4113 (cf deploy --secrets-file)
cf migrate needs a local wrangler#4112

Also observed, not matched to an issue number: --dry-run omits bindings.secret() from the binding list, and there is no offline verify path (--local unsupported). Setup that worked: a vite.config.mts plus cloudflare.config.ts with domains and a D1 binding; secrets only through bindings.secret() + the secret upload, never in config.

Core t1k-cloudflare (cf commands, auth, gaps), t1k-datastore-cost (pre-deploy cost check), rule gamebackend-game-server-invariants. Shared credentials are read from the studio vault, never pasted into a repo or chat.