t1k:gamebackend:game-server:template-bootstrap
| Field | Value |
|---|---|
| Module | game-server |
| Version | 1.10.3 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/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/GameServerTemplateis a real private repo, default branchmain(read 2026-10-09 withgit ls-remote/gh api).maincarries the section runtime (src/core/runtime/), the identity context, thered-proofsrunner and, since PR #3 (5c6b4d6), the SteelBorn hardening (atomic rate limiter + migration 0002,If-Match400, zero-amount no-op, JWT header guard). It has no CI workflow and no branch protection: runbun test(--maxWorkers) yourself before trusting a ref. Its root holdssetup.sh,cloudflare.config.ts,src/,test/,migrations/,scripts/,types/,vite.config.mts,.env.example,CONTRIBUTING.md,CHANGELOG.md. Prefersetup.sh(slug, domain, DO-class rename) over the manual table below; read the template’s README and itsCHANGELOG.md“Unreleased” first and trust them over this list. Seam check, runtime guards,setup.shfailure 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.mjsflow is what a game repo adds — a server that IS its own repo root pulls core withgit checkout template/main -- src/coreper the template’sCONTRIBUTING.md):references/core-guards-and-pull-flow.md.
Decision tree
Section titled “Decision tree”| Intent | Go 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 |
Place it: server/ in the game repo
Section titled “Place it: server/ in the game repo”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:
- 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 templatefirst, andgit read-tree --prefix=server/ -u template/main(or agit archive template/main | tar -x -C server/when the working tree is busy).setup.shstages work too: it edits files relative to its own directory, so run it from insideserver/(cd server && ./setup.sh --yes --slug <game> --domain <game>-api.the1studio.org), never from the repo root with a path argument. - One
corepin per server. Aserver/subdirectory is the monorepo case inreferences/core-guards-and-pull-flow.md§ “Pull flow inside a monorepo subdirectory”:git checkout template/main -- src/coredoes NOT resolve from the game-repo root, so ship.template-pin.json+core-files.sha256+scripts/sync-template.shatserver/and letserver/’s ownbun testrunverify-core-pin.mjs. - Ignore the server’s build output from the GAME root. The repo root
.gitignoreneeds the server’snode_modules/,dist/,.cf/,.dev.vars,.wrangler/; the template’s own.gitignorecovers them only if something reads it, and a root-level client build does not. Check withgit status --porcelain server/after abun install --frozen-lockfile+bun test: it must be empty but for files you intended. - Root docs name the subdirectory. The game’s
AGENTS.md/CLAUDE.mdsays the server isserver/(Hono + Zod + TypeScript on Workers,cfdeploys, GOP source of truth for its own commands) and points atserver/AGENTS.mdfor the rest, so an agent working on the Unity project does not go hunting for a separate server repo. - 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.
Preconditions
Section titled “Preconditions”- Node.js 22.18.0 or newer (the
cfconfig loader needsmodule.registerHooks). cfpinned as a devDependency (the studio pin is in coret1k-cloudflare, itsbeta-caveats-and-fallbackreference file);cf auth whoamiworks, orCLOUDFLARE_API_TOKEN+CLOUDFLARE_ACCOUNT_IDare set (the env token wins over a stored profile).- A brand domain for the API, declared in
cloudflare.config.tsfrom the first deploy. Never*.workers.devor 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).
Rename the template
Section titled “Rename the template”Change these together, in one commit, before the first deploy:
| What | Where | Note |
|---|---|---|
| Worker name | cloudflare.config.ts worker.name, package.json name | one Worker per game and environment |
| API host | cloudflare.config.ts worker.domains | brand domain, e.g. <game>-api.the1studio.org |
| D1 directory name | bindings.d1({ name }) and the cf d1 create below | resource commands take ids, not names |
APP_SERVER_ID (optional) text binding | bindings.text(...) in config, or leave it out | per-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 |
compatibilityDate | cloudflare.config.ts | do 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.exports | see below |
Provision and deploy
Section titled “Provision and deploy”All write commands accept --dry-run; run it first and read the method, URL and body.
- D1 directory.
cf d1 create --name <game>-directory, note the id. Apply migrations:cf d1 migrations apply <database>(--dir,--pattern,--tableexist; list pending withcf d1 migrations list <database>; create one withcf d1 migrations create <message>). There is nocf d1 importand no--file: send SQL throughcf d1 query <database-id> --sql "..."or report the gap. - Secrets — first deploy uses the secrets FILE. The template’s README and the
setup.shnext-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 bulkneeds 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>"}}, thencf workers secrets bulk --worker <name> --body @<file> --dry-runwith a placeholder body first, then the real call, then delete the file.--text <value>puts the secret on argv (visible inpsand history): throwaway values only.cfcannot set a single secret yet. Unlisted secrets are untouched;nulldeletes one. - Local run. Copy
.env.exampleto.dev.vars(git-ignored) and fill it;cf dev. Production values are Worker secrets and never enter git. - Dry run.
cf deploy --dry-run. It proves build and config resolve. It does not surfacebindings.secret()values, so it does not prove the secrets exist in the target account. - 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-pluginplusvite.config.mts), elsecf deploy --dry-runexits early with “No Cloudflare dev-server is installed in this project.” - Smoke the brand domain:
GET /health(unauthenticated liveness),POST /connect/tokenfor 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 bulkis for later only. Whether the--secrets-fileformat 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 (cfis beta): confirm on your first deploy. - Tests before every deploy:
bun testwith a worker cap (--maxWorkers=4; the workstation is shared, never two full suites at once).
Irreversible: never rename the DO class
Section titled “Irreversible: never rename the DO class”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.
cf gaps to report (not work around)
Section titled “cf gaps to report (not work around)”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.
| Observed | Core 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.
Related
Section titled “Related”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.