@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/DEPLOY.md

@@ -0,0 +1,2012 @@
+# Deploying the Babylon Game Server
+
+This guide takes `@babylonjs-toolkit/server` (the Babylon Game Server) from `npx` on a laptop to a production
+deployment. It covers how the server ships, how to choose a topology, what to set before players arrive, one step-by-step
+recipe per host, and how to run and troubleshoot it once it is live.
+
+It assumes you know Node.js and Docker basics. You do not need to know this codebase. Every option, environment variable,
+flag, endpoint and template file named here exists in the package; the [README](README.md) is the full option reference.
+
+`babylon-game-server init` also writes a short `DEPLOY.md` into the starter folder, next to the recipe files. This guide
+covers the same recipes in more depth, and the two agree.
+
+> **Recommended host: [Colyseus Cloud](#411-colyseus-cloud).** The server is built on Colyseus 0.18, and Colyseus
+> Cloud is Colyseus's own hosting: a fixed monthly price per machine, `wss://` and its certificate provided, one server
+> process per CPU sharing Redis with no setup, rolling deploys that let running sessions finish, and player and room
+> statistics and alerts on its panel. The server detects Colyseus Cloud and configures itself for it. Every other
+> recipe below runs the same server anywhere else.
+
+> **Before you rely on a cloud recipe:** the AWS, Fly.io, Railway, Render, DigitalOcean, Heroku and Kubernetes recipes
+> have been parsed and tested, and the Colyseus Cloud recipe has been rehearsed with Colyseus's own deploy scripts, but
+> none has been deployed to a real cloud account yet. Try your recipe on a staging account first, especially the AWS NLB
+> `TCP_QUIC` recipe. See [Known limitations](#known-limitations).
+
+Throughout this guide, `<version>` means the server package version you install, for example `9.30.1`. The image tag,
+the npm version and the version that `init` writes into its recipes are always the same number.
+
+## Contents
+
+1. [How it ships](#1-how-it-ships)
+   - [The npm package and the CLI](#the-npm-package-and-the-cli)
+   - [The starter folder (`init`)](#the-starter-folder-init)
+   - [The Docker image](#the-docker-image)
+   - [Configuring a container](#configuring-a-container)
+   - [Building your own image](#building-your-own-image)
+   - [Pushing to a registry](#pushing-to-a-registry)
+   - [Pinning versions and upgrading](#pinning-versions-and-upgrading)
+2. [Choosing a topology](#2-choosing-a-topology)
+   - [Where TLS ends](#where-tls-ends)
+   - [WebSocket only, or WebSocket + UDP](#websocket-only-or-websocket--udp)
+   - [One instance, or scale-out with Redis](#one-instance-or-scale-out-with-redis)
+   - [Dedicated sessions need CPU and memory](#dedicated-sessions-need-cpu-and-memory)
+   - [Decision table](#decision-table)
+   - [What each host supports](#what-each-host-supports)
+3. [The production checklist](#3-the-production-checklist)
+4. [Recipes](#4-recipes)
+   - [4.1 Local and development](#41-local-and-development)
+   - [4.2 A plain VM (Docker or systemd)](#42-a-plain-vm-docker-or-systemd)
+   - [4.3 Docker Compose](#43-docker-compose)
+   - [4.4 AWS](#44-aws)
+   - [4.5 Kubernetes](#45-kubernetes)
+   - [4.6 Fly.io](#46-flyio)
+   - [4.7 Railway](#47-railway)
+   - [4.8 Render](#48-render)
+   - [4.9 DigitalOcean App Platform](#49-digitalocean-app-platform)
+   - [4.10 Heroku](#410-heroku)
+   - [4.11 Colyseus Cloud](#411-colyseus-cloud)
+5. [Serving dedicated-session scenes](#5-serving-dedicated-session-scenes)
+6. [Operating it](#6-operating-it)
+7. [Connecting the game](#7-connecting-the-game)
+8. [Troubleshooting deployment](#8-troubleshooting-deployment)
+9. [Known limitations](#known-limitations)
+
+---
+
+## 1. How it ships
+
+The server ships two ways: as an npm package with a CLI, and as a multi-architecture Docker image. Both run the same
+code. The server holds no game code: it loads the Babylon Toolkit runtime headless, with Babylon Toolkit Networking built
+in, and a game's own classes stay in its `PROJECT` script bundle. One server deployment can therefore host any number of
+games that speak the same network protocol version.
+
+### The npm package and the CLI
+
+| Item | Value |
+|---|---|
+| Package | `@babylonjs-toolkit/server` |
+| Runtime | Node.js 22 or newer (`"engines": { "node": ">=22" }`) |
+| CLI | `babylon-game-server` (`lib/cli.js`) |
+| Library entry | `createGameServer`, `loadGameServerConfig` and the other exports of `lib/index.js` |
+| Optional native package | `@colyseus/h3-transport`, needed only for UDP (HTTP/3 WebTransport) |
+
+Run it without installing:
+
+```sh
+npx @babylonjs-toolkit/server
+# Babylon Game Server <version> listening on ws://localhost:2567
+#   HTTP:         http://localhost:2567
+#   WebTransport: off
+#   TLS: off   UDP: off   Auth: off   Redis: off
+```
+
+Or install it into a project and use the CLI from there:
+
+```sh
+npm install @babylonjs-toolkit/server@<version>
+npx babylon-game-server            # start (the default command)
+```
+
+The CLI has three commands:
+
+| Command | What it does | Exit codes |
+|---|---|---|
+| `babylon-game-server [start] [flags]` | Starts the server. `start` is optional. | `2` on a configuration problem (every problem is printed at once), `1` on any other startup failure, `0` after a clean drain. |
+| `babylon-game-server init [folder] [--force]` | Writes the starter folder (default `./babylon-game-server`). | `1` when any file already existed and was kept (`skipped (exists)`); run again with `--force` to overwrite. |
+| `babylon-game-server healthcheck [flags]` | GETs `/game-server/health` on `127.0.0.1` at the configured port, over `https` when TLS is on (the certificate is not checked). | `0` on HTTP 200, else `1`. The Docker image's `HEALTHCHECK` runs it. |
+
+Notes for installing on a server rather than in a container:
+
+- **`npm install` needs `git`.** A Colyseus dependency (`uWebSockets.js`) is fetched from GitHub, which is why the
+  repository's `Dockerfile` installs `git` in its build stage.
+- **UDP needs the optional native package.** `@colyseus/h3-transport` is installed automatically where its native build
+  succeeds. Where it does not, a server started with UDP stops with
+  `UDP needs @colyseus/h3-transport, which is not installed on this platform`. WebSocket-only servers never need it.
+- **There is no `--version` flag** (unknown flags are refused with exit code 2). The version is in the startup banner,
+  in `npm ls @babylonjs-toolkit/server`, and in `serverVersion` of `GET /game-server/info`.
+
+**Running from code.** `createGameServer({ config, hooks, routes, handleSignals })` starts the same server inside your
+own Node program. It reads no file or environment unless you call `loadGameServerConfig` yourself, and it drains on
+`SIGTERM`/`SIGINT` only when you pass `handleSignals: true` (the CLI does). You need this only for `custom` auth (a
+`verifyToken` hook), lifecycle hooks or extra HTTP routes. One game server runs per process.
+
+```ts
+import { createGameServer, loadGameServerConfig } from "@babylonjs-toolkit/server";
+
+const config = await loadGameServerConfig({ argv: process.argv.slice(2), environment: process.env, workingDirectory: process.cwd() });
+await createGameServer({ config, handleSignals: true, hooks: { /* verifyToken, onSessionCreated, ... */ } });
+```
+
+### The starter folder (`init`)
+
+```sh
+npx babylon-game-server init            # writes ./babylon-game-server/
+npx babylon-game-server init deploy     # or into ./deploy/
+```
+
+`init` copies every file of the package's `templates/init/` folder, replacing `{{version}}` with the installed package
+version (so every image reference is pinned to the exact version you installed), and generates `.env.example` from the
+option table. TLS, UDP and auth are off in every file it writes.
+
+| File | What it is |
+|---|---|
+| `babylon-game-server.config.mjs` | Every setting at its default, with comments on enabling TLS, UDP, auth and dedicated sessions. |
+| `.env.example` | Every option as a `GAME_SERVER_*` variable with its default; secrets and unset options are left empty. |
+| `Dockerfile` | Your image: `FROM ghcr.io/mackeyk24/babylon-game-server:<version>` plus your config file. |
+| `DEPLOY.md` | The short deployment guide for this folder. |
+| `docker-compose.websocket.yml`, `Caddyfile` | The server behind Caddy: HTTPS at Caddy, WebSocket only. |
+| `docker-compose.full.yml` | TLS on the server, WebSocket + HTTP/3 on 443 TCP + UDP, and Redis. |
+| `aws/README.md`, `aws/ecs-fargate-alb.yml`, `aws/ecs-fargate-nlb-quic.yml` | AWS: ECS Fargate behind an ALB or an NLB with QUIC; single-EC2 and Elastic Beanstalk notes. |
+| `kubernetes/deployment.yaml`, `kubernetes/service.yaml`, `kubernetes/redis.yaml` | Kubernetes Deployment, ClusterIP Service and an in-cluster Redis. |
+| `fly.toml`, `railway.json`, `render.yaml`, `digitalocean-app.yaml`, `heroku.yml`, `app.json` | Platform recipes. |
+
+Each recipe file starts with a header that states where TLS ends (`edge` or `server`), whether its host can carry UDP,
+and how to turn on auth.
+
+> `.env.example` sets `GAME_SERVER_PORT=2567`. On a platform that sets `PORT` (Heroku, Railway, Render), remove that line
+> if you copy the file into the platform's variables, because `GAME_SERVER_PORT` wins over `PORT`. Empty variables count
+> as unset, so the empty lines are harmless.
+
+### The Docker image
+
+| Property | Value |
+|---|---|
+| Image | `ghcr.io/mackeyk24/babylon-game-server:<version>` (also on Docker Hub as `mackeyk24/babylon-game-server:<version>`) |
+| Platforms | `linux/amd64` and `linux/arm64` |
+| Base | `node:22-bookworm-slim` |
+| User | `node` (uid 1000), not root |
+| Environment | `NODE_ENV=production` (JSON logs, development certificates refused) |
+| Ports | `EXPOSE 2567/tcp 2567/udp` |
+| Entrypoint | `node /app/SVR/lib/cli.js` (the CLI; arguments after the image name go to it) |
+| Health check | `HEALTHCHECK --interval=15s --timeout=5s --start-period=20s CMD ["node","/app/SVR/lib/cli.js","healthcheck"]` |
+| Working directory | `/app` |
+
+```sh
+docker run --rm -p 2567:2567 ghcr.io/mackeyk24/babylon-game-server:<version>
+curl -s http://localhost:2567/game-server/health     # {"status":"ok"}
+```
+
+### Configuring a container
+
+Settings come from, highest first: command-line flags, `GAME_SERVER_*` environment variables, a config file, the
+defaults. In a container, use **environment variables** or a **mounted config file**, not flags:
+
+- **Environment variables** are the simplest and what every recipe uses. `PORT` is read when `GAME_SERVER_PORT` is unset.
+  List variables are comma-separated. Booleans accept `true`/`false`, `1`/`0`, `yes`/`no`.
+- **A mounted config file** is named by `GAME_SERVER_CONFIG` (`.mjs`, `.js` or `.json`). Without it, the server looks
+  for `babylon-game-server.config.mjs`, `.js` or `.json` in its working directory (`/app` in the image). The dedicated
+  session settings (`dedicated.scenes`, `dedicated.boot`) exist only in a config file.
+
+```sh
+docker run -d -p 2567:2567 \
+  -v "$PWD/babylon-game-server.config.mjs:/app/config/babylon-game-server.config.mjs:ro" \
+  -e GAME_SERVER_CONFIG=/app/config/babylon-game-server.config.mjs \
+  ghcr.io/mackeyk24/babylon-game-server:<version>
+```
+
+Why not flags: the image's `HEALTHCHECK` runs `healthcheck` with the container's environment but **without** the flags
+you passed to the start command. A port given only as `--port 3000` makes the health check call 2567 and report the
+container unhealthy. Anything set by environment or config file is seen by both.
+
+Unknown config-file keys, unknown flags and wrongly typed values are refused at startup with exit code 2 and a list of
+every problem, each naming the option and its environment variable. (Environment variables the server does not know are
+simply ignored, so check the spelling of every `GAME_SERVER_*` name.)
+
+### Building your own image
+
+**From the starter folder (recommended).** The init `Dockerfile` adds your config to the published image:
+
+```dockerfile
+FROM ghcr.io/mackeyk24/babylon-game-server:<version>
+COPY babylon-game-server.config.mjs /app/config/
+ENV GAME_SERVER_CONFIG=/app/config/babylon-game-server.config.mjs
+# Local dedicated scenes (exported glTF folders) referenced by dedicated.scenes[].sceneRoot:
+# COPY scenes/ /app/scenes/
+```
+
+```sh
+cd babylon-game-server
+docker build -t my-game-server .
+docker run --rm -p 2567:2567 my-game-server
+```
+
+Build for both architectures when the target differs from your machine (for example an Apple Silicon laptop building
+for x86 Fargate, which the AWS templates use):
+
+```sh
+docker buildx build --platform linux/amd64,linux/arm64 -t <registry>/my-game-server:<version> --push .
+```
+
+Keep secrets out of the config file you bake in: put them in the platform's secret store and pass them as environment
+variables, which override the file.
+
+**From the Babylon Toolkit repository.** `SVR/Dockerfile` builds the image itself from source. It must be built from the
+repository root, because it copies the runtime bundle in `UMD/`; `SVR/Dockerfile.dockerignore` limits the build context
+to `UMD/package.json`, `UMD/lib/**`, `SVR/package.json`, `SVR/tsconfig.json`, `SVR/src/**` and `SVR/templates/**`.
+
+```sh
+# 1. Build the runtime bundle the server loads.
+cd APP && npm run build-ts && npm run combine-umd && npm run build-umd && cd ..
+# 2. Build the image from the repository root.
+docker build -f SVR/Dockerfile -t babylon-game-server .
+# Multi-architecture, as the release does:
+docker buildx build --platform linux/amd64,linux/arm64 -f SVR/Dockerfile -t <registry>/babylon-game-server:<version> --push .
+```
+
+The Dockerfile runs `npm install` (not `npm ci`) because lock files are git-ignored in that repository; the server's
+direct dependencies are exact pins. The release script `npm run release:image` (in `SVR/`) runs the `buildx` command
+above with tags `ghcr.io/mackeyk24/babylon-game-server:$npm_package_version` and
+`mackeyk24/babylon-game-server:$npm_package_version`; it is for the package maintainer.
+
+### Pushing to a registry
+
+Most platforms can pull `ghcr.io/mackeyk24/babylon-game-server` directly (it is public). Push a copy to your own registry
+when you build your own image, when your network cannot reach ghcr.io (for example private subnets without a NAT
+gateway), or when policy requires it. `docker buildx imagetools create` copies the published multi-architecture image
+without pulling it:
+
+**Amazon ECR**
+
+```sh
+AWS_REGION=us-east-1
+ACCOUNT=123456789012
+REPO=$ACCOUNT.dkr.ecr.$AWS_REGION.amazonaws.com/babylon-game-server
+aws ecr create-repository --repository-name babylon-game-server --region $AWS_REGION
+aws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin $ACCOUNT.dkr.ecr.$AWS_REGION.amazonaws.com
+
+# Mirror the published image (both architectures):
+docker buildx imagetools create --tag $REPO:<version> ghcr.io/mackeyk24/babylon-game-server:<version>
+# Or push your own image built from the init Dockerfile:
+docker buildx build --platform linux/amd64,linux/arm64 -t $REPO:<version> --push .
+```
+
+Then pass `Image=$REPO:<version>` to the AWS templates.
+
+**GitHub Container Registry**
+
+```sh
+echo "$GITHUB_TOKEN" | docker login ghcr.io -u <your-github-user> --password-stdin   # a token with write:packages
+docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/<your-github-user>/my-game-server:<version> --push .
+```
+
+**Docker Hub**
+
+```sh
+docker login
+docker buildx build --platform linux/amd64,linux/arm64 -t <your-docker-user>/my-game-server:<version> --push .
+```
+
+### Pinning versions and upgrading
+
+**Always pin an exact version.** Use the exact tag `init` wrote (`ghcr.io/mackeyk24/babylon-game-server:<version>`), not
+`latest` or a short tag, and install `@babylonjs-toolkit/server@<version>` exactly. The package version follows the
+Babylon Toolkit runtime it ships with (`babylonjs-toolkit`): the published package depends on that exact runtime version
+and its exact Babylon.js versions.
+
+**Protocol versions.** The server and the game's Babylon Toolkit runtime share a **network protocol version**
+(`TOOLKIT.NETWORK_PROTOCOL_VERSION`), separate from package versions. Check the server's with:
+
+```sh
+curl -s https://game.example.com/game-server/info
+# {"serverName":"Babylon Game Server","serverVersion":"<version>","protocolVersion":1,"transports":{...},"authRequired":true}
+```
+
+- Releases that keep the protocol version can be mixed freely: upgrade the server and the game independently.
+- A release that changes it says so in its notes. Then upgrade the server and the game together. A game on another
+  protocol version is refused at matchmaking with `IncompatibleConfiguration`, naming both versions and the side to
+  update; the game also checks `/game-server/info` before it joins.
+
+**To upgrade:**
+
+1. Read the release notes for a protocol version change.
+2. Update the version everywhere `init` pinned it: the `FROM` line of `Dockerfile`, the default image in
+   `docker-compose.websocket.yml` and `docker-compose.full.yml` (or `GAME_SERVER_IMAGE`), the `image:` of
+   `kubernetes/deployment.yaml`, and the `Image` parameter of the AWS templates (pass `Image=...:<new version>`). For an
+   npm install, `npm install @babylonjs-toolkit/server@<new version>`.
+3. To see what changed in the recipes, write a fresh starter folder beside yours (`npx babylon-game-server init
+   starter-<new version>`) and diff it. Do not run `init --force` over your edited folder; it overwrites your config.
+4. Redeploy with a rolling update. Running sessions finish on the old instance while it drains (see
+   [Rolling updates](#rolling-updates-and-draining)).
+
+---
+
+## 2. Choosing a topology
+
+### Where TLS ends
+
+Browsers block `ws://` from an `https://` page, so production players need `wss://`. TLS can end in one of two places:
+
+| | TLS at the edge | TLS on the server |
+|---|---|---|
+| Who holds the certificate | Caddy, a cloud load balancer (ALB), or the platform (Fly, Railway, Render, DigitalOcean, Heroku, an Ingress) | The game server itself (`tls.enabled` with `tls.certFile`/`tls.keyFile` or `tls.certPem`/`tls.keyPem`) |
+| Server settings | TLS off (the default); usually `trustProxy: true` | `GAME_SERVER_TLS_ENABLED=true` plus a certificate |
+| Certificate renewal | The proxy or platform does it | Files are reloaded automatically; see [Certificate renewal](#certificate-renewal) |
+| UDP (HTTP/3) possible | **No** | **Yes** (with a host that forwards UDP) |
+| Use it when | You want WebSocket only and managed certificates | You want UDP, or the server is the public endpoint with no proxy |
+
+HTTP/3 always uses TLS, and the QUIC connection must end at the server, so a proxy that terminates TLS in front of it
+cannot carry UDP. That is the whole reason to terminate TLS on the server.
+
+### WebSocket only, or WebSocket + UDP
+
+With UDP on (`GAME_SERVER_UDP_ENABLED=true`), the server also accepts WebTransport over HTTP/3 on the same port number,
+UDP beside TCP. Unreliable frames (snapshots, inputs, acks and unreliable RPCs) then travel as datagrams, so one lost
+packet no longer holds up the ones behind it. Reliable frames and frames over 1000 bytes keep the reliable stream.
+
+UDP is an improvement, not a requirement. Players whose browser or network cannot use WebTransport connect over
+WebSocket and play in the same session, so a WebSocket-only host is fully playable.
+
+UDP needs all of:
+
+- TLS on the server itself (the config refuses `udp.enabled` without `tls.enabled`).
+- The port open for **UDP as well as TCP** at every layer: firewall, security group, `docker run -p 443:443/udp`.
+- A host that forwards inbound UDP to the server, on the **same public port number as the `wss://` URL**. The game
+  opens WebTransport to the host and port of its server URL, so `wss://game.example.com` means UDP 443.
+- A browser with WebTransport: Chrome and Edge 97+, Firefox 115+, Safari 26.4+. Others use WebSocket.
+- `@colyseus/h3-transport` installed (it is in the Docker image).
+
+Which hosts can carry UDP:
+
+| Can carry UDP | Cannot (WebSocket only) |
+|---|---|
+| VMs and bare metal (AWS EC2, DigitalOcean Droplets, Hetzner and similar); Docker Compose on a VM with `docker-compose.full.yml`; AWS ECS behind a Network Load Balancer with a `TCP_QUIC` listener (`aws/ecs-fargate-nlb-quic.yml`); Kubernetes with server TLS and a LoadBalancer Service that forwards TCP and UDP | Caddy (`docker-compose.websocket.yml`); AWS ALB (`aws/ecs-fargate-alb.yml`) and Elastic Beanstalk; Fly.io; Railway; Render; DigitalOcean App Platform; Heroku; Colyseus Cloud; a Kubernetes HTTP Ingress |
+
+### One instance, or scale-out with Redis
+
+**One process hosts many sessions** (up to `limits.maxSessions`, default 1000), and **a session always lives in one
+process**. Start with one instance; most games never need more for relayed (Shared, Host/Client) sessions, which only
+forward messages.
+
+To run several instances behind one address, every instance needs:
+
+1. **The same Redis**: `GAME_SERVER_REDIS_URL=redis://...` on every instance. Matchmaking on any instance then finds
+   every session, the lobby lists every instance's sessions, and the admin API sees and closes all of them.
+2. **Its own public address**: `GAME_SERVER_PUBLIC_ADDRESS=<host>[:<port>]`, an address players can reach **that one
+   instance** on directly. A player who matchmakes on instance A for a session held by instance B is sent to B's public
+   address (the seat reservation names it).
+
+How the public address is used, which matters for TLS:
+
+- Once `publicAddress` is set, **every** seat reservation that instance makes carries it, even with one instance, and
+  the browser connects to it with the scheme of the game's server URL: `wss://<publicAddress>` when the game uses
+  `wss://`. So the address must serve TLS with a certificate valid for that host name whenever players use `wss://`.
+- A private IP (a pod IP, a VPC address) works only for players on that network.
+- With TLS at a shared edge (one load balancer or one platform host name), you cannot give each instance its own
+  address, so **keep one instance per address** there. That is why the AWS templates say to keep `DesiredCount=1`, and
+  why the PaaS recipes run one instance.
+
+Scale-out patterns that satisfy the rule:
+
+| Pattern | Each instance's public address |
+|---|---|
+| Several VMs, TLS on each server | `game-1.example.com`, `game-2.example.com`, each with its own certificate (or a wildcard) |
+| Several processes on one VM, TLS on each server | `game.example.com:2567`, `game.example.com:2568`, ... (open each port for TCP, and UDP if used) |
+| Several AWS stacks, each `DesiredCount=1` with its own domain | `game-1.example.com` → stack 1's load balancer, and so on, all sharing one ElastiCache |
+| Kubernetes StatefulSet with one LoadBalancer Service per pod | Each Service's external host name |
+
+The game can use any instance's address as its `serverUrl`; matchmaking finds sessions everywhere.
+
+Readiness answers 503 while Redis does not answer, so a load balancer stops sending new players to an instance that
+cannot matchmake.
+
+### Dedicated sessions need CPU and memory
+
+The session types cost very different amounts:
+
+| Session type | What the server does | Cost |
+|---|---|---|
+| Shared, Host/Client, AutoHostOrClient | Relays messages; keeps Shared-mode state | Light: network and a little CPU per message |
+| Dedicated (Server mode) | Loads the exported scene headless (Babylon.js `NullEngine` with Havok, no materials or textures) and simulates it every tick | Heavy: a full scene simulation per session |
+
+All sessions of one process share **one JavaScript thread**. Adding vCPUs to one container does not let one process run
+more dedicated sessions; adding processes (instances) does. Memory grows with each loaded scene.
+
+There are no published sizing figures. Size by measurement:
+
+1. Start with the templates' sizes: Fargate `Cpu: "512"`, `Memory: "1024"`; Kubernetes requests `cpu: 250m`,
+   `memory: 512Mi`, limit `memory: 1Gi`; DigitalOcean `apps-s-1vcpu-1gb`.
+2. Run your heaviest scene with the expected player count, and watch
+   `babylon_game_server_dedicated_frame_seconds` and `babylon_game_server_dedicated_tick_overruns_total` (frames longer
+   than one simulation tick), plus the process memory and event-loop lag metrics. See [Metrics](#metrics).
+3. Set `limits.maxDedicatedSessions` (default 4) to what one instance sustains without overruns. Joins beyond it are
+   refused with `MaxCcuReached`, which is better than every session on the instance falling behind.
+
+### Decision table
+
+| You need | Topology | Recipe |
+|---|---|---|
+| To try it locally | One process, no TLS | [Local](#41-local-and-development) |
+| **The recommended production host**: managed, fixed price, several processes behind one address with Redis provided | One process per CPU, TLS at the platform edge, WebSocket | [Colyseus Cloud](#411-colyseus-cloud) |
+| A managed server from a Docker image | One instance, TLS at the platform edge, WebSocket | [Fly.io](#46-flyio), [Railway](#47-railway), [Render](#48-render), [DigitalOcean](#49-digitalocean-app-platform), [Heroku](#410-heroku) |
+| A cheap VM you control, WebSocket only | One instance behind Caddy | [Compose + Caddy](#websocket-behind-caddy) |
+| The best network feel (UDP datagrams) on one machine | One instance, TLS on the server, TCP + UDP 443 | [Compose full](#tls-http3-and-redis) or [single EC2](#single-ec2-instance-with-an-elastic-ip) |
+| AWS-managed, WebSocket only | ECS Fargate + ALB, TLS at the ALB | [ECS + ALB](#ecs-fargate-behind-an-application-load-balancer) |
+| AWS-managed with UDP | ECS Fargate + NLB `TCP_QUIC`, TLS on the server | [ECS + NLB QUIC](#ecs-fargate-behind-a-network-load-balancer-with-quic) |
+| More sessions than one process holds | Several instances, shared Redis, one public address each | [Scale-out](#one-instance-or-scale-out-with-redis) |
+| Many dedicated (Server-mode) sessions | Several instances sized by measurement, `limits.maxDedicatedSessions` per instance | [Dedicated sizing](#dedicated-sessions-need-cpu-and-memory) |
+| An existing Kubernetes cluster | Deployment + Ingress (WebSocket), or server TLS + UDP LoadBalancer | [Kubernetes](#45-kubernetes) |
+
+### What each host supports
+
+| Host (template) | TLS | UDP | Scale-out | Health check in the template | Stop timeout in the template |
+|---|---|---|---|---|---|
+| Docker Compose + Caddy (`docker-compose.websocket.yml`) | edge (Caddy) | no | one host | the image's `HEALTHCHECK` | Docker's default 10 s; add `stop_grace_period` |
+| Docker Compose full (`docker-compose.full.yml`) | server | yes (443/udp) | Redis included; add instances with their own addresses | the image's `HEALTHCHECK` | Docker's default 10 s; add `stop_grace_period` |
+| AWS ECS Fargate + ALB (`aws/ecs-fargate-alb.yml`) | edge (ALB) | no | `DesiredCount=1` per stack | target group `/game-server/ready` | `StopTimeout: 45` |
+| AWS ECS Fargate + NLB (`aws/ecs-fargate-nlb-quic.yml`) | server | yes (`TCP_QUIC`) | `DesiredCount=1` per stack | target group HTTPS `/game-server/ready` | `StopTimeout: 45` |
+| AWS single EC2 + Elastic IP (`aws/README.md`) | server | yes | one per address | the image's `HEALTHCHECK` | `docker stop` default 10 s; pass `--stop-timeout` |
+| AWS Elastic Beanstalk (`aws/README.md`) | edge (ALB) | no | one instance | set to `/game-server/ready` | platform default |
+| Kubernetes (`kubernetes/`) | edge (Ingress) or server | only with server TLS + UDP LoadBalancer | Redis + one reachable address per pod | liveness `/game-server/health`, readiness `/game-server/ready` | `terminationGracePeriodSeconds: 45` |
+| Fly.io (`fly.toml`) | edge | no | one machine | `/game-server/ready` | `kill_timeout = "45s"` |
+| Railway (`railway.json`) | edge | no | `numReplicas: 1` | `/game-server/ready` | platform default |
+| Render (`render.yaml`) | edge | no | `numInstances: 1` | `/game-server/ready` | platform default |
+| DigitalOcean App Platform (`digitalocean-app.yaml`) | edge | no | `instance_count: 1` | `/game-server/ready` | platform default |
+| Heroku (`heroku.yml`, `app.json`) | edge | no | one dyno | none (router) | 30 s, so `GAME_SERVER_DRAIN_SECONDS=25` |
+| Colyseus Cloud (`colyseus-cloud/`) | edge | no | Redis, one process per CPU | listening socket (PM2 ready signal) | `kill_timeout` 30 min in the template, drain 600 s |
+
+---
+
+## 3. The production checklist
+
+Set each of these before players arrive. A complete environment for a WebSocket server behind a TLS edge looks like
+this; every recipe below shows where to put it.
+
+```sh
+NODE_ENV=production                                        # the image sets it
+GAME_SERVER_TRUST_PROXY=true                               # only behind your own proxy (see 5)
+GAME_SERVER_AUTH_ENABLED=true
+GAME_SERVER_AUTH_MODE=jwt
+GAME_SERVER_AUTH_JWT_JWKS_URL=https://login.example.com/.well-known/jwks.json
+GAME_SERVER_AUTH_JWT_ISSUER=https://login.example.com/
+GAME_SERVER_AUTH_JWT_AUDIENCE=my-game
+GAME_SERVER_ALLOWED_ORIGINS=https://game.example.com
+GAME_SERVER_ADMIN_TOKEN=<from your secret store>           # a secret
+GAME_SERVER_METRICS_REQUIRE_ADMIN_TOKEN=true
+GAME_SERVER_ADMIN_ALLOWED_NETWORKS=203.0.113.0/24          # who may reach the admin console (see 13)
+GAME_SERVER_PUBLIC_URL=wss://game.example.com              # shown in the banner
+GAME_SERVER_DRAIN_SECONDS=30                               # stop timeout must be longer (see 9)
+```
+
+### 1. `NODE_ENV=production`
+
+**Why:** it switches `logFormat: "auto"` to JSON lines, refuses development certificates
+(`tls.developmentCertificate`), and makes the server warn at startup when auth is off on an address other machines can
+reach.
+**How:** the Docker image sets it. For an npm install, set it in the service environment (systemd `Environment=`).
+
+### 2. TLS
+
+**Why:** browsers refuse `ws://` from `https://` pages, and tokens must not travel in clear text.
+**How:** terminate TLS at the edge (Caddy, a load balancer, the platform) and leave server TLS off, or turn on server TLS
+for UDP or when the server is the public endpoint:
+
+```sh
+GAME_SERVER_TLS_ENABLED=true
+GAME_SERVER_TLS_CERT_FILE=/certs/fullchain.pem      # PEM chain, reloaded when it changes
+GAME_SERVER_TLS_KEY_FILE=/certs/privkey.pem
+# or the PEM text itself, from a secret store:
+GAME_SERVER_TLS_CERT_PEM="$(cat fullchain.pem)"
+GAME_SERVER_TLS_KEY_PEM="$(cat privkey.pem)"
+```
+
+Set one pair, not both: when both are set, the PEM text is the one served. The container runs as `node` (uid 1000), so
+the key file must be readable by that user.
+
+### 3. Authentication
+
+**Why:** with auth off, anyone who can reach the server can create and join sessions.
+**How:** set `GAME_SERVER_AUTH_ENABLED=true` and a mode. Every join (sessions and the lobby) must then carry a token,
+verified at matchmaking before a seat is reserved. The game passes it as `startGame({ authToken })`.
+
+| Mode (`GAME_SERVER_AUTH_MODE`) | Settings | Good for | Identity the host sees |
+|---|---|---|---|
+| `shared-secret` | `GAME_SERVER_AUTH_SHARED_SECRET_TOKENS=token-one,token-two` | Private builds, playtests, server-to-server | `{ userId: null, claims: { method: "shared-secret", keyIndex } }` |
+| `jwt` with a JWKS | `GAME_SERVER_AUTH_JWT_JWKS_URL`, optionally `..._ISSUER`, `..._AUDIENCE`, `..._ALGORITHMS` | Players signed in with Auth0, Cognito, Firebase, Clerk or similar | `{ userId: <sub>, claims: <payload> }` |
+| `jwt` with an HMAC secret | `GAME_SERVER_AUTH_JWT_SECRET` (HS256/384/512), optionally `..._ISSUER`, `..._AUDIENCE` | Your own backend signs short-lived tokens | `{ userId: <sub>, claims: <payload> }` |
+| `webhook` | `GAME_SERVER_AUTH_WEBHOOK_URL`, `GAME_SERVER_AUTH_WEBHOOK_TIMEOUT_MS` (default 5000) | Your service approves each player; no code in the server | `{ userId: body.userId ?? null, claims: body }` |
+| `custom` | A `verifyToken` hook passed to `createGameServer` | Your own verifier in code ([Running from code](#the-npm-package-and-the-cli)) | What your hook returns |
+| Discord sign-in (beside any mode, or with auth off) | `GAME_SERVER_DISCORD_SIGN_IN_ENABLED=true`, `GAME_SERVER_DISCORD_CLIENT_ID`, `GAME_SERVER_DISCORD_CLIENT_SECRET`, `GAME_SERVER_DISCORD_REDIRECT_URI` (registered in the Discord application as `https://<server>/game-server/discord/callback`), `GAME_SERVER_DISCORD_RETURN_ORIGINS` | Players who sign in with their Discord account; the server issues its own session token (README, "Discord sign-in") | `{ userId: "discord:<id>", claims: { sub, name, avatar, provider: "discord", name_managed: true } }` |
+
+Deployment notes:
+
+- **JWKS:** the server must reach the JWKS URL over outbound HTTPS. Keys are fetched on the first join, cached for
+  10 minutes, and refetched (at most every 30 seconds) when a token names an unknown key.
+- **Webhook:** the server POSTs JSON `{ token, kind, sessionName, gameMode, clientAddress, origin }` and waits up to
+  `GAME_SERVER_AUTH_WEBHOOK_TIMEOUT_MS`. A 2xx answer with a JSON object admits the player; anything else refuses. Keep
+  the webhook close to the server (same region) so the timeout is not spent on the network.
+- **Custom** cannot be set from the environment alone: `auth.mode "custom" needs a verifyToken hook`. Use `webhook`
+  when you want your own logic without writing a server entry script.
+- Tokens are compared in constant time and never logged.
+
+### 4. `allowedOrigins`
+
+**Why:** limits which web pages can use your server. It also sets the CORS answer, so a browser on another origin cannot
+call the server at all.
+**How:** list your game's origins exactly as the browser sends them (scheme, host and port, no path):
+
+```sh
+GAME_SERVER_ALLOWED_ORIGINS=https://game.example.com,https://www.game.example.com
+```
+
+Empty (the default) allows any origin. `GAME_SERVER_ALLOW_MISSING_ORIGIN` (default `true`) accepts joins that send no
+`Origin` header, which native clients and tools do; set it to `false` if only browsers should join.
+With Discord sign-in on, every origin in `GAME_SERVER_DISCORD_RETURN_ORIGINS` must also be one of the game's origins listed here.
+
+### 5. `trustProxy`
+
+**Why:** the per-address join limit and the logs use the client address. Behind a proxy, every player otherwise appears
+as the proxy's address and they all share one join-rate allowance (120 joins per minute by default). Trusting the
+forwarding headers on a server that clients reach directly would let any client choose its address.
+**How:**
+
+| Situation | `GAME_SERVER_TRUST_PROXY` |
+|---|---|
+| Behind Caddy, an ALB, an Ingress, Fly, Render, DigitalOcean App Platform, Heroku (they set `X-Forwarded-For`) | `true` (the Caddy, ALB, Fly, Render, DigitalOcean and Heroku templates set it) |
+| Public directly: TLS on the server, no proxy (Compose full, single EC2) | `false` (the default) |
+| Behind an NLB or a TCP LoadBalancer Service (TCP passthrough, no forwarding headers) | `false`; preserve the client IP at the load balancer instead (see the AWS and Kubernetes recipes) |
+
+### 6. The admin token
+
+**Why:** the admin API lists and closes sessions, starts dedicated sessions and drains the server. It is off (404) until
+a token is set.
+**How:** generate a long random value, keep it in your secret store, and pass it as `GAME_SERVER_ADMIN_TOKEN`:
+
+```sh
+openssl rand -hex 32
+```
+
+Admin calls send `Authorization: Bearer <token>`; a wrong or missing token answers 401. The admin paths
+(`/game-server/admin/...`) are served on the public port. If your proxy can filter paths, you can also block them at the
+edge and call them from inside your network.
+
+### 7. Protect `/metrics`
+
+**Why:** `/metrics` is on by default and public unless you protect it. It reveals player counts, session counts and
+refusal reasons.
+**How:** pick one:
+
+- `GAME_SERVER_METRICS_REQUIRE_ADMIN_TOKEN=true` **together with** `GAME_SERVER_ADMIN_TOKEN` (without an admin token,
+  every request then gets 403). Your Prometheus sends the token as a bearer token.
+- Block `/metrics` at the proxy and scrape the instance on its private address.
+- `GAME_SERVER_METRICS_ENABLED=false` (then `/metrics` answers 404).
+
+### 8. Health vs readiness probes
+
+**Why:** they answer different questions. Wiring readiness as liveness gets a healthy, draining server killed.
+
+| Endpoint | Answers | Use it for |
+|---|---|---|
+| `GET /game-server/health` | 200 `{ "status": "ok" }` while the process serves HTTP | **Liveness**: restart the container when it fails. The image's `HEALTHCHECK` uses it. |
+| `GET /game-server/ready` | 200 `{ "ready": true }`, or 503 `{ "ready": false, "reasons": [...] }` with `draining`, `redis unreachable` or `not listening` | **Readiness / load-balancer routing**: stop sending new players there |
+
+Platforms with a single health check (Fly, Railway, Render, DigitalOcean, the AWS target groups) use
+`/game-server/ready` in the templates, so a draining instance leaves rotation.
+
+### 9. Stop timeout vs `drainSeconds`
+
+**Why:** on `SIGTERM` (or `SIGINT`) the server stops taking joins, lets running sessions continue for up to
+`drainSeconds` (default 30), tells the remaining players the session closed (`GameClosed`) and exits 0. A watchdog exits
+1 if that takes longer than `drainSeconds` + 5 seconds. If the platform kills the process first (`SIGKILL`), sessions are
+cut without the `GameClosed` message.
+**How:** give the platform's stop timeout at least `drainSeconds` + 10 seconds, or lower `drainSeconds` to fit the
+platform:
+
+| Platform | Setting | Template value |
+|---|---|---|
+| ECS | container `StopTimeout` (Fargate maximum 120) | `45` |
+| Kubernetes | `terminationGracePeriodSeconds` | `45` |
+| Fly.io | `kill_timeout` | `"45s"` |
+| Heroku | fixed 30 s | `GAME_SERVER_DRAIN_SECONDS=25` in `app.json` |
+| `docker run` / `docker stop` | `--stop-timeout 45` / `docker stop -t 45` | not set (Docker's default is 10 s) |
+| Docker Compose | `stop_grace_period: 45s` on the `game-server` service | not set (default 10 s) |
+| systemd | `TimeoutStopSec=45` | see [the unit below](#systemd) |
+| Colyseus Cloud | PM2's `kill_timeout`, which `@colyseus/tools` sets to 30 minutes | `drainSeconds` defaults to 600 on this host |
+| Railway, Render, DigitalOcean App Platform | the platform's shutdown grace period | not set: check the platform's documentation and keep `drainSeconds` below it |
+
+The drain finishes early when every session has ended, so a long `drainSeconds` costs nothing on a quiet server. The
+exception is a process holding a `boot` dedicated session: that session never empties, so the process drains for the full
+`drainSeconds`.
+
+### 10. Limits
+
+**Why:** abuse limits are on by default; check them against your game.
+**How:**
+
+| Variable | Default | Change it when |
+|---|---|---|
+| `GAME_SERVER_MAX_SESSIONS` | `1000` | You want to cap one process lower (refused with 503 `MaxCcuReached`) |
+| `GAME_SERVER_MAX_PLAYERS_PER_SESSION` | `255` | You want a hard cap below what games request (larger requests are clamped) |
+| `GAME_SERVER_MAX_DEDICATED_SESSIONS` | `4` | Measured capacity of one instance (see [sizing](#dedicated-sessions-need-cpu-and-memory)) |
+| `GAME_SERVER_JOIN_REQUESTS_PER_MINUTE` | `120` | Many players legitimately share one address (offices, events) |
+| `GAME_SERVER_MAX_MESSAGE_BYTES` | `65536` | Your game sends larger reliable messages (the connection closes over it) |
+| `GAME_SERVER_MAX_MESSAGES_PER_SECOND` | `2000` | A client legitimately sends more (it is disconnected over it) |
+| `GAME_SERVER_MAX_SESSION_NAME_LENGTH` | `128` | Your session names are longer |
+
+Every refusal is counted in `babylon_game_server_refusals_total{reason}` and logged as `join refused`.
+
+### 11. Logging
+
+**Why:** you need searchable logs when something goes wrong.
+**How:** in production, logs are one JSON object per line (`{"time":...,"level":...,"message":...}` plus
+`sessionName`, `roomId`, `playerId`, `userId` and `clientAddress` when known). Errors and warnings go to stderr, the rest
+to stdout; the startup banner is plain text. Force a format with `GAME_SERVER_LOG_FORMAT=json` or `text`, and set
+`GAME_SERVER_LOG_LEVEL` (`error`, `warn`, `info` (default), `debug`). Use `debug` only while investigating.
+
+### 12. Secrets
+
+**Why:** tokens and keys in an image or a committed file leak.
+**How:** these options are secrets, are never logged, and belong in your platform's secret store, passed as environment
+variables:
+
+| Secret | Variable |
+|---|---|
+| Admin token | `GAME_SERVER_ADMIN_TOKEN` |
+| Admin console single sign-on client secret | `GAME_SERVER_ADMIN_OIDC_CLIENT_SECRET` |
+| Shared-secret player tokens | `GAME_SERVER_AUTH_SHARED_SECRET_TOKENS` |
+| JWT HMAC secret | `GAME_SERVER_AUTH_JWT_SECRET` |
+| Discord sign-in client secret | `GAME_SERVER_DISCORD_CLIENT_SECRET` |
+| TLS certificate and key text | `GAME_SERVER_TLS_CERT_PEM`, `GAME_SERVER_TLS_KEY_PEM` |
+| Redis URL (it carries the password) | `GAME_SERVER_REDIS_URL` |
+
+Environment variables override the config file, so keep the config file free of secrets and commit it safely. Where to
+put them: `fly secrets set`, Railway / Render / DigitalOcean / Heroku encrypted variables, AWS Secrets Manager through the
+task definition's `Secrets`, a Kubernetes `Secret` through `valueFrom.secretKeyRef`, or a root-owned `EnvironmentFile`
+on a VM.
+
+### 13. The admin console
+
+**Why:** the console at `/game-server/admin/` can kick and ban players, close sessions, change limits and drain the
+fleet, and its data (accounts, bans, the audit log) must outlive the container.
+**How:** before players arrive:
+
+- **HTTPS.** The console and its API refuse plain HTTP (403 `the console needs HTTPS`) except from a loopback address.
+  Serve them on your TLS address: TLS on the server, or a TLS edge with `GAME_SERVER_TRUST_PROXY=true` that sends
+  `x-forwarded-proto: https` (Caddy, an ALB, an Ingress and the PaaS hosts do).
+- **A data volume or Redis.** Without Redis the console keeps its data in files under `GAME_SERVER_ADMIN_DATA_DIR`; the
+  image sets it to `/data` and declares a volume there. Mount a named volume (`-v game-server-data:/data`, as the
+  compose files and `fly.toml` do). With `GAME_SERVER_REDIS_URL` set, the data lives in Redis instead and every instance
+  shares it: give Redis persistence (append-only file, as `docker-compose.full.yml` and `kubernetes/redis.yaml` do, or
+  a managed Redis with backups). Hosts without volumes (Railway, Render, DigitalOcean App Platform, Heroku, ECS
+  Fargate) need Redis, or the console forgets its accounts on every deploy. The leaderboards live there too (README,
+  "Leaderboards"), so the same rule keeps the boards and scores; the console's Leaderboards page warns when they are not
+  durable, and its Settings tab exports a backup.
+- **`allowedNetworks`.** Set `GAME_SERVER_ADMIN_ALLOWED_NETWORKS` to your office or VPN addresses or CIDR ranges; other
+  addresses get 404 from every console path. Or block `/game-server/admin/` at the edge and reach it from inside your
+  network. Behind a proxy this needs `trustProxy`, so the forwarded address is the one checked.
+- **The first Owner.** The first start logs `admin setup link` at `warn`, valid for 30 minutes and usable once: open its
+  path (`/game-server/admin/#/setup?token=…`) on your HTTPS address. Or create the Owner where the data is:
+  `docker exec -it <container> node /app/SVR/lib/cli.js admin create-owner --username <name>`. Each account then signs
+  in with a password and an authenticator code or passkey; keep the recovery codes safe.
+- **Backups of the data folder.** Copy the data folder or snapshot its volume on a schedule (or turn on Redis backups):
+  it holds the bans and the tamper-evident audit log. The CLI (`babylon-game-server admin …`) works on the same store
+  when nobody can sign in.
+
+README, "Admin console", has the roles, API keys and security advice.
+
+---
+
+## 4. Recipes
+
+Every recipe below states its TLS, UDP and scaling support. Commands use `game.example.com` as your domain and
+`<version>` as the server version.
+
+### 4.1 Local and development
+
+**TLS:** off, or a local development certificate. **UDP:** yes, locally. **Scaling:** one process.
+
+```sh
+npx @babylonjs-toolkit/server                          # ws://localhost:2567
+npx @babylonjs-toolkit/server --port 3000 --log-level debug
+```
+
+The game connects to `ws://localhost:2567` from an `http://` page.
+
+**Local TLS and UDP.** To test `wss://` and WebTransport on one machine without a real certificate:
+
+```sh
+brew install mkcert && mkcert -install                 # once; see mkcert's docs for Linux and Windows
+npx @babylonjs-toolkit/server --tls --tls-dev-cert --udp
+# Babylon Game Server <version> listening on wss://localhost:2567
+#   HTTP:         https://localhost:2567
+#   WebTransport: https://localhost:2567
+#   TLS: on (development)   UDP: on (WebTransport on https://localhost:2567, UDP 2567)   Auth: off   Redis: off
+```
+
+- HTTPS and WSS use an mkcert certificate for `localhost`, `127.0.0.1` and `::1`, made once and cached in the OS temp
+  folder (`babylon-game-server-dev-cert`). It does not cover other host names, so phones and other machines on your LAN
+  cannot use it.
+- HTTP/3 uses its own 10-day self-signed certificate whose SHA-256 hash the server publishes in `/game-server/info` and
+  at matchmaking, so the browser pins it (browsers refuse WebTransport to locally trusted roots such as mkcert's). It is
+  made fresh at every start.
+- Without mkcert, `--tls --tls-dev-cert --udp` still works: the pinned certificate serves HTTPS too. `--tls --tls-dev-cert`
+  without `--udp` stops with `install mkcert (brew install mkcert && mkcert -install) or set tls.certFile/keyFile`.
+- Development certificates are refused when `NODE_ENV=production`, so this does not work in the Docker image.
+
+**Local Redis scale-out test** (two processes, one machine):
+
+```sh
+redis-server --save "" --appendonly no --port 6379 &
+GAME_SERVER_REDIS_URL=redis://localhost:6379 GAME_SERVER_PUBLIC_ADDRESS=localhost:2567 npx babylon-game-server --port 2567 &
+GAME_SERVER_REDIS_URL=redis://localhost:6379 GAME_SERVER_PUBLIC_ADDRESS=localhost:2568 npx babylon-game-server --port 2568 &
+```
+
+**Stopping:** `Ctrl-C` drains like `SIGTERM`: with sessions running it waits up to `drainSeconds`. Press `Ctrl-C` again
+to quit at once, or start with `--drain-seconds 0`.
+
+### 4.2 A plain VM (Docker or systemd)
+
+**TLS:** server (or edge with your own proxy). **UDP:** yes, with server TLS. **Scaling:** one instance per public
+address; several with Redis.
+
+Open TCP 443 (and UDP 443 for HTTP/3) in the VM's firewall and the provider's security group, and point your domain's DNS
+at the VM.
+
+#### Certificates with certbot
+
+```sh
+sudo certbot certonly --standalone -d game.example.com      # needs TCP 80 free during issue and renewal
+```
+
+The files under `/etc/letsencrypt/live/game.example.com/` are readable only by root. Copy them where the server's user
+can read them, on every renewal, with a deploy hook. For the Docker image (user `node`, uid 1000):
+
+```sh
+sudo mkdir -p /srv/game/certs
+sudo tee /etc/letsencrypt/renewal-hooks/deploy/babylon-game-server.sh >/dev/null <<'EOF'
+#!/bin/sh
+install -m 0644 -o 1000 -g 1000 "$RENEWED_LINEAGE/fullchain.pem" /srv/game/certs/fullchain.pem
+install -m 0600 -o 1000 -g 1000 "$RENEWED_LINEAGE/privkey.pem"   /srv/game/certs/privkey.pem
+EOF
+sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/babylon-game-server.sh
+sudo RENEWED_LINEAGE=/etc/letsencrypt/live/game.example.com /etc/letsencrypt/renewal-hooks/deploy/babylon-game-server.sh
+```
+
+The server polls the files every 30 seconds and reloads them for HTTPS and WSS without a restart. With UDP on, HTTP/3
+keeps the old certificate until the next restart (the server logs `HTTP/3 uses the new certificate after a restart`), so
+add `docker restart game-server` (or `systemctl restart babylon-game-server`) to the hook when UDP is on.
+
+#### Docker
+
+```sh
+docker run -d --name game-server --restart unless-stopped --stop-timeout 45 \
+  -p 443:443/tcp -p 443:443/udp \
+  -v /srv/game/certs:/certs:ro \
+  -e GAME_SERVER_PORT=443 \
+  -e GAME_SERVER_TLS_ENABLED=true \
+  -e GAME_SERVER_TLS_CERT_FILE=/certs/fullchain.pem \
+  -e GAME_SERVER_TLS_KEY_FILE=/certs/privkey.pem \
+  -e GAME_SERVER_UDP_ENABLED=true \
+  -e GAME_SERVER_ALLOWED_ORIGINS=https://game.example.com \
+  --env-file /srv/game/secrets.env \
+  ghcr.io/mackeyk24/babylon-game-server:<version>
+```
+
+`/srv/game/secrets.env` holds the secrets (`GAME_SERVER_ADMIN_TOKEN=...`, auth settings), readable only by root. Drop
+`GAME_SERVER_UDP_ENABLED` and `-p 443:443/udp` for WebSocket only. Players use `wss://game.example.com`.
+
+To put Caddy or your own proxy in front instead (WebSocket only, TLS at the proxy), use the
+[Compose + Caddy recipe](#websocket-behind-caddy).
+
+#### systemd
+
+Without Docker, install Node.js 22+ and `git`, then:
+
+```sh
+sudo useradd --system --create-home --home-dir /opt/babylon-game-server game
+cd /opt/babylon-game-server
+sudo -u game npm install @babylonjs-toolkit/server@<version>
+sudo -u game npx babylon-game-server init .           # writes the config and .env.example here
+sudo install -m 0600 -o root -g root .env.example /etc/babylon-game-server.env   # then edit it
+```
+
+`/etc/systemd/system/babylon-game-server.service`:
+
+```ini
+[Unit]
+Description=Babylon Game Server
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+User=game
+WorkingDirectory=/opt/babylon-game-server
+Environment=NODE_ENV=production
+EnvironmentFile=/etc/babylon-game-server.env
+ExecStart=/usr/bin/node /opt/babylon-game-server/node_modules/@babylonjs-toolkit/server/lib/cli.js
+KillSignal=SIGTERM
+# drainSeconds (30) plus a margin
+TimeoutStopSec=45
+Restart=on-failure
+# Exit code 2 is a configuration problem: restarting will not fix it.
+RestartPreventExitStatus=2
+# Only when the server itself binds 443:
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```sh
+sudo systemctl daemon-reload
+sudo systemctl enable --now babylon-game-server
+journalctl -u babylon-game-server -f
+```
+
+The server finds `babylon-game-server.config.mjs` in its `WorkingDirectory`. In the environment file, empty values
+count as unset, so the copied `.env.example` is a safe starting point. For TLS on the server, point
+`GAME_SERVER_TLS_CERT_FILE` / `GAME_SERVER_TLS_KEY_FILE` at copies readable by the `game` user (adapt the certbot hook
+above to `-o root -g game` with mode `0640` for the key).
+
+**Behind nginx instead of Caddy** (not shipped as a template; WebSocket only, set `GAME_SERVER_TRUST_PROXY=true` and
+`GAME_SERVER_HOST=127.0.0.1` so only nginx reaches the server):
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:2567;
+    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 3600s;
+}
+```
+
+### 4.3 Docker Compose
+
+Both compose files read `GAME_SERVER_IMAGE` when it is set, so you can try a locally built image first
+(`GAME_SERVER_IMAGE=my-game-server docker compose ...`). Both mount `./babylon-game-server.config.mjs` into the server.
+
+Neither file sets a stop grace period, so `docker compose down` and restarts give the server Docker's default 10 seconds
+before `SIGKILL`, shorter than the 30-second drain. Add one to the `game-server` service:
+
+```yaml
+services:
+  game-server:
+    stop_grace_period: 45s
+```
+
+#### WebSocket behind Caddy
+
+`docker-compose.websocket.yml` + `Caddyfile`. **TLS:** edge (Caddy gets and renews a certificate for your domain).
+**UDP:** no (Caddy proxies TCP). **Scaling:** one server.
+
+The server publishes no ports of its own; only Caddy reaches it on the compose network. The server runs with
+`GAME_SERVER_TRUST_PROXY: "true"`, because Caddy forwards the player's address.
+
+1. Point your domain's DNS at the host and open TCP 443.
+2. Put production settings in the config file, or add them under `environment:` in the compose file (secrets through an
+   `env_file:` that you do not commit).
+3. Start it:
+
+```sh
+CADDY_SITE=game.example.com docker compose -f docker-compose.websocket.yml up -d
+# players use wss://game.example.com
+```
+
+Local check without a domain (plain HTTP on 8080):
+
+```sh
+CADDY_SITE=:8080 docker compose -f docker-compose.websocket.yml up -d
+curl -s http://localhost:8080/game-server/health     # {"status":"ok"}
+docker compose -f docker-compose.websocket.yml down
+```
+
+The compose file publishes `${CADDY_HTTP_PORT:-443}:443` and `8080:8080`; port 80 is not published, so Caddy obtains its
+certificate over 443 (TLS-ALPN) and there is no automatic `http://` → `https://` redirect.
+
+#### TLS, HTTP/3 and Redis
+
+`docker-compose.full.yml`. **TLS:** server. **UDP:** yes (443/udp published). **Scaling:** Redis is included and wired
+(`GAME_SERVER_REDIS_URL: redis://redis:6379`), ready for more instances.
+
+1. Get a certificate into `./certs` (`fullchain.pem`, `privkey.pem`) readable by uid 1000, as in
+   [Certificates with certbot](#certificates-with-certbot) (copy into `./certs` instead of `/srv/game/certs`).
+2. Open TCP **and** UDP 443 on the host and its firewall.
+3. Start it:
+
+```sh
+docker compose -f docker-compose.full.yml up -d
+```
+
+Players use `wss://game.example.com`; browsers that support WebTransport switch to HTTP/3 datagrams automatically and
+fall back to the WebSocket when UDP is blocked.
+
+Notes:
+
+- The server listens on 443 directly (`GAME_SERVER_PORT: "443"`) as the non-root `node` user; current Docker engines
+  allow that inside the container's network namespace.
+- With one server, Redis only adds a dependency: readiness answers 503 if it goes down. Remove `GAME_SERVER_REDIS_URL`
+  and the `redis` service if you will never add a second instance. To add one on another host, point it at this Redis
+  (do not expose Redis to the internet; use a private network) and give **both** servers a `GAME_SERVER_PUBLIC_ADDRESS`
+  that reaches each one directly with a valid certificate (for example `game-1.example.com` and `game-2.example.com`).
+- The Redis container runs without a password and is reachable only on the compose network.
+
+### 4.4 AWS
+
+| Setup | Template | TLS | UDP | Scaling |
+|---|---|---|---|---|
+| ECS Fargate + Application Load Balancer | `aws/ecs-fargate-alb.yml` | edge (ALB, ACM certificate) | no | `DesiredCount=1` per stack |
+| ECS Fargate + Network Load Balancer `TCP_QUIC` | `aws/ecs-fargate-nlb-quic.yml` | server (PEM from Secrets Manager) | yes | `DesiredCount=1` per stack |
+| One EC2 instance + Elastic IP | `aws/README.md` | server | yes | one per address |
+| Elastic Beanstalk | `aws/README.md` notes | edge (ALB) | no | one instance |
+
+Both CloudFormation templates take the same parameters:
+
+| Parameter | Meaning | Default |
+|---|---|---|
+| `VpcId` | The VPC the load balancer and the tasks run in | required |
+| `SubnetIds` | Two or more **public** subnets in different availability zones | required |
+| `CertificateArn` | ALB template: the ACM certificate for your domain. NLB template: not used (kept so both take the same parameters) | required (ALB) / `""` (NLB) |
+| `TlsSecretArn` | NLB template only: Secrets Manager secret with `certPem` and `keyPem` | required (NLB) |
+| `Image` | The server image | `ghcr.io/mackeyk24/babylon-game-server:<version>` |
+| `DesiredCount` | Number of server tasks | `1` |
+
+Both create: an ECS cluster, a CloudWatch Logs group (14-day retention), a task execution role, a Fargate task definition
+(`Cpu: "512"`, `Memory: "1024"`, x86_64, `StopTimeout: 45`, `GAME_SERVER_LOG_FORMAT=json`), security groups, the load
+balancer, a target group (`TargetType: ip`, health check `/game-server/ready`, deregistration delay 45 s) and the service
+(tasks get a public IP so they can pull from ghcr.io without a NAT gateway). Output: `LoadBalancerDnsName` (the ALB
+template also outputs `HealthUrl`).
+
+The templates have no parameters for auth, origins, the admin token or Redis. Add them to the container's
+`Environment` (plain values) and `Secrets` (from Secrets Manager) in the template before deploying; see
+[Adding settings to the templates](#adding-settings-to-the-ecs-templates).
+
+#### ECR (your own image)
+
+See [Pushing to a registry](#pushing-to-a-registry). The task definitions do not set a CPU architecture, so Fargate runs
+them on x86_64: the image must include `linux/amd64`. The task execution role's managed policy
+(`AmazonECSTaskExecutionRolePolicy`) already allows pulling from ECR in the same account.
+
+#### ACM and Route 53
+
+Request a certificate (ALB recipe) in the **stack's region**, validated by DNS:
+
+```sh
+aws acm request-certificate --domain-name game.example.com --validation-method DNS --region us-east-1
+aws acm describe-certificate --certificate-arn <arn> --region us-east-1 \
+  --query "Certificate.DomainValidationOptions[0].ResourceRecord"
+# create that CNAME in your DNS (Route 53 can do it from the ACM console), then:
+aws acm wait certificate-validated --certificate-arn <arn> --region us-east-1
+```
+
+After the stack is up, point your domain at the load balancer:
+
+```sh
+LB=$(aws cloudformation describe-stacks --stack-name babylon-game-server \
+  --query "Stacks[0].Outputs[?OutputKey=='LoadBalancerDnsName'].OutputValue" --output text)
+aws route53 change-resource-record-sets --hosted-zone-id <your zone id> --change-batch '{
+  "Changes": [{ "Action": "UPSERT", "ResourceRecordSet": {
+    "Name": "game.example.com", "Type": "CNAME", "TTL": 300, "ResourceRecords": [{ "Value": "'"$LB"'" }] } }] }'
+```
+
+An alias A record works too (it needs the load balancer's hosted zone id from `aws elbv2 describe-load-balancers`).
+
+#### ECS Fargate behind an Application Load Balancer
+
+`aws/ecs-fargate-alb.yml`. **TLS:** edge (ALB, ACM). **UDP:** no (ALB listeners are HTTP/HTTPS only). **Scaling:**
+`DesiredCount=1` per stack.
+
+The ALB listens on HTTPS 443 (`SslPolicy: ELBSecurityPolicy-TLS13-1-2-2021-06`) and forwards to the tasks on 2567. Its
+idle timeout is raised to 3600 seconds so quiet WebSockets are not cut. The tasks accept 2567 only from the ALB's
+security group, and the container sets `GAME_SERVER_TRUST_PROXY=true` because the ALB forwards the player's address.
+
+```sh
+aws cloudformation deploy \
+  --template-file aws/ecs-fargate-alb.yml \
+  --stack-name babylon-game-server \
+  --capabilities CAPABILITY_IAM \
+  --parameter-overrides \
+    VpcId=vpc-0123456789abcdef0 \
+    SubnetIds=subnet-aaaa,subnet-bbbb \
+    CertificateArn=arn:aws:acm:us-east-1:123456789012:certificate/... \
+    DesiredCount=1
+```
+
+Then create the DNS record, and check:
+
+```sh
+curl -s https://game.example.com/game-server/ready      # {"ready":true}
+curl -s https://game.example.com/game-server/info
+```
+
+Set the game's `serverUrl` to `wss://game.example.com`.
+
+#### ECS Fargate behind a Network Load Balancer with QUIC
+
+`aws/ecs-fargate-nlb-quic.yml`. **TLS:** server. **UDP:** yes (`TCP_QUIC` listener). **Scaling:** `DesiredCount=1` per
+stack.
+
+A `TCP_QUIC` listener on 443 passes TCP and QUIC through to a `TCP_QUIC` target group on 2567, and the server terminates
+TLS itself with `GAME_SERVER_TLS_ENABLED=true`, `GAME_SERVER_UDP_ENABLED=true`, and the certificate injected from
+Secrets Manager as `GAME_SERVER_TLS_CERT_PEM` / `GAME_SERVER_TLS_KEY_PEM`. The target group checks HTTPS
+`/game-server/ready`.
+
+1. **Get a certificate whose private key you hold** (the server needs the PEM key, so a certificate that lives only in
+   ACM on a load balancer will not do). For example with certbot and its Route 53 DNS plugin:
+
+   ```sh
+   certbot certonly --dns-route53 -d game.example.com
+   ```
+
+2. **Store it** as one JSON secret with the keys `certPem` and `keyPem`:
+
+   ```sh
+   aws secretsmanager create-secret --name babylon-game-server-tls \
+     --secret-string "$(jq -n --rawfile certPem fullchain.pem --rawfile keyPem privkey.pem '{certPem: $certPem, keyPem: $keyPem}')"
+   ```
+
+3. **Deploy:**
+
+   ```sh
+   aws cloudformation deploy \
+     --template-file aws/ecs-fargate-nlb-quic.yml \
+     --stack-name babylon-game-server-quic \
+     --capabilities CAPABILITY_IAM \
+     --parameter-overrides \
+       VpcId=vpc-0123456789abcdef0 \
+       SubnetIds=subnet-aaaa,subnet-bbbb \
+       TlsSecretArn=arn:aws:secretsmanager:us-east-1:123456789012:secret:babylon-game-server-tls-AbCdEf
+   ```
+
+4. **Point your domain** at the `LoadBalancerDnsName` output. The certificate must cover that domain.
+
+Notes:
+
+- **Check QUIC support first.** QUIC listeners on Network Load Balancers are newer than the rest of this setup. Check the
+  current Elastic Load Balancing documentation for QUIC listener and target requirements in your region before you
+  depend on it.
+- **Security groups.** QUIC listeners cannot have security groups, so the task security group admits 2567 TCP and UDP
+  from `0.0.0.0/0`.
+- **Client addresses.** There is no proxy header on this path, so `trustProxy` stays off. Check in the logs
+  (`clientAddress`) that players appear with their own addresses. If they all appear as load balancer addresses, every
+  player shares one join-rate allowance: turn on client IP preservation on the target group
+  (`preserve_client_ip.enabled`, if your target type and protocol support it) or raise
+  `GAME_SERVER_JOIN_REQUESTS_PER_MINUTE`.
+- **Certificate rotation.** The secret is read at task start. After renewing, update the secret and roll the service:
+
+  ```sh
+  aws secretsmanager put-secret-value --secret-id babylon-game-server-tls \
+    --secret-string "$(jq -n --rawfile certPem fullchain.pem --rawfile keyPem privkey.pem '{certPem: $certPem, keyPem: $keyPem}')"
+  CLUSTER=$(aws cloudformation describe-stack-resource --stack-name babylon-game-server-quic --logical-resource-id Cluster \
+    --query StackResourceDetail.PhysicalResourceId --output text)
+  SERVICE=$(aws cloudformation describe-stack-resource --stack-name babylon-game-server-quic --logical-resource-id Service \
+    --query StackResourceDetail.PhysicalResourceId --output text)
+  aws ecs update-service --cluster "$CLUSTER" --service "$SERVICE" --force-new-deployment
+  ```
+
+#### Single EC2 instance with an Elastic IP
+
+**TLS:** server. **UDP:** yes. **Scaling:** one instance per address. The most direct way to offer HTTP/3: the
+instance's address receives TCP and UDP 443 itself.
+
+1. Launch an instance (for example Amazon Linux 2023, `t4g.small`) with Docker installed, and associate an Elastic IP.
+   Point your domain at the Elastic IP.
+2. In its security group, open **TCP 443 and UDP 443** to `0.0.0.0/0` (and TCP 80 if certbot uses the HTTP challenge).
+3. Get a certificate and copy it into a folder readable by uid 1000, as in
+   [Certificates with certbot](#certificates-with-certbot).
+4. Run the image with TLS and UDP, with `docker-compose.full.yml` or the `docker run` command in
+   [A plain VM](#docker). The `aws/README.md` command is the same without `--stop-timeout`; add it.
+
+`t4g` instances are arm64; the image includes `linux/arm64`.
+
+#### Elastic Beanstalk
+
+**TLS:** edge (ALB). **UDP:** no. **Scaling:** one instance.
+
+- Use the **Docker** platform and deploy the starter folder with its `Dockerfile` (`eb init -p docker`, `eb create`).
+- Beanstalk puts an Application Load Balancer in front: attach your ACM certificate to a 443 HTTPS listener, forward to
+  instance port 2567, set the health check path to `/game-server/ready`, and raise the ALB idle timeout to 3600 s so
+  WebSockets are not cut.
+- Set `GAME_SERVER_TRUST_PROXY=true` and your production settings as environment properties.
+- The Beanstalk Docker platform can run its own proxy on the instance between the load balancer and the container.
+  Check that a real game client connects (WebSocket upgrades reach the server) before relying on it; a passing health
+  check does not prove that.
+
+#### ElastiCache for Redis
+
+Needed only for scale-out. Create a Redis-compatible cache **with cluster mode disabled** (the server opens one Redis
+connection from a URL; it does not create a cluster client) in the same VPC, and allow TCP 6379 from the task security
+group. Then:
+
+```sh
+GAME_SERVER_REDIS_URL=redis://<primary endpoint>:6379                       # no in-transit encryption
+GAME_SERVER_REDIS_URL=rediss://:<auth token>@<primary endpoint>:6379        # in-transit encryption + AUTH
+```
+
+Pass it from Secrets Manager (it carries the password). Remember the
+[public address rule](#one-instance-or-scale-out-with-redis): Redis alone does not let you raise `DesiredCount` behind
+one load balancer. Run one stack per instance, each with its own domain, `DesiredCount=1`, the same Redis URL and
+`GAME_SERVER_PUBLIC_ADDRESS` set to that stack's domain.
+
+Test the URL before deploying: with wrong credentials the server never starts listening (see
+[Troubleshooting](#8-troubleshooting-deployment)).
+
+#### Adding settings to the ECS templates
+
+Edit the `ContainerDefinitions` entry of the template. Plain values go in `Environment`; secrets in `Secrets`, which
+reads a Secrets Manager secret (or a JSON key of one, as the NLB template does):
+
+```yaml
+          Environment:
+            - Name: GAME_SERVER_LOG_FORMAT
+              Value: json
+            - Name: GAME_SERVER_TRUST_PROXY      # ALB template only
+              Value: "true"
+            - Name: GAME_SERVER_ALLOWED_ORIGINS
+              Value: https://game.example.com
+            - Name: GAME_SERVER_AUTH_ENABLED
+              Value: "true"
+            - Name: GAME_SERVER_AUTH_MODE
+              Value: jwt
+            - Name: GAME_SERVER_AUTH_JWT_JWKS_URL
+              Value: https://login.example.com/.well-known/jwks.json
+            - Name: GAME_SERVER_METRICS_REQUIRE_ADMIN_TOKEN
+              Value: "true"
+          Secrets:
+            - Name: GAME_SERVER_ADMIN_TOKEN
+              ValueFrom: arn:aws:secretsmanager:us-east-1:123456789012:secret:babylon-game-server-admin-AbCdEf
+```
+
+The ALB template's `TaskExecutionRole` has no Secrets Manager permission. When you add `Secrets` to it, add a policy like
+the NLB template's `read-tls-secret`:
+
+```yaml
+      Policies:
+        - PolicyName: read-game-server-secrets
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: secretsmanager:GetSecretValue
+                Resource: arn:aws:secretsmanager:us-east-1:123456789012:secret:babylon-game-server-*
+```
+
+#### CloudWatch logs
+
+The container logs with the `awslogs` driver to the stack's log group, stream prefix `game-server`, as JSON lines.
+
+```sh
+GROUP=$(aws cloudformation describe-stack-resource --stack-name babylon-game-server --logical-resource-id LogGroup \
+  --query StackResourceDetail.PhysicalResourceId --output text)
+aws logs tail "$GROUP" --follow
+```
+
+A CloudWatch Logs Insights query for refused joins:
+
+```text
+fields time, level, message, sessionName, clientAddress
+| filter message = "join refused"
+| sort @timestamp desc
+```
+
+#### IAM the templates need
+
+- **To deploy** (your user or CI role): CloudFormation, plus create/update/delete rights on what the stack makes: ECS
+  (cluster, task definition, service), IAM (the unnamed task execution role, so the deploy needs
+  `--capabilities CAPABILITY_IAM`, and `iam:PassRole` for it), EC2 security groups, Elastic Load Balancing (load
+  balancer, target group, listener) and CloudWatch Logs (log group). Use an administrator role for the first deploy in
+  a sandbox account, then narrow it to these services.
+- **Task execution role** (created by the stack): the managed `AmazonECSTaskExecutionRolePolicy` (pull from ECR, write
+  to CloudWatch Logs). The NLB template adds `secretsmanager:GetSecretValue` on `TlsSecretArn`. If your secret is
+  encrypted with a customer-managed KMS key, also allow `kms:Decrypt` on that key.
+- **Task role:** none. The server calls no AWS APIs.
+
+### 4.5 Kubernetes
+
+`kubernetes/`. **TLS:** edge (Ingress) or server. **UDP:** only with server TLS and a LoadBalancer Service that forwards
+TCP and UDP. **Scaling:** Redis plus one player-reachable address per pod.
+
+What the manifests contain:
+
+| File | Contents |
+|---|---|
+| `deployment.yaml` | Deployment `babylon-game-server`, 1 replica, image `ghcr.io/mackeyk24/babylon-game-server:<version>`, port `game` 2567/TCP, `runAsNonRoot` as uid 1000, `terminationGracePeriodSeconds: 45`, liveness `/game-server/health`, readiness `/game-server/ready`, requests `cpu: 250m` / `memory: 512Mi`, limit `memory: 1Gi`. Environment: `GAME_SERVER_PUBLIC_ADDRESS: "$(POD_IP):2567"` (pod IP from the downward API), `GAME_SERVER_REDIS_URL: redis://babylon-game-server-redis:6379`, `GAME_SERVER_LOG_FORMAT: json`. |
+| `service.yaml` | ClusterIP Service `babylon-game-server` on 2567/TCP, for an Ingress |
+| `redis.yaml` | A single `redis:7` Deployment and ClusterIP Service `babylon-game-server-redis`, no persistence |
+
+```sh
+kubectl apply -f kubernetes/redis.yaml -f kubernetes/deployment.yaml -f kubernetes/service.yaml
+kubectl rollout status deployment/babylon-game-server
+kubectl port-forward deployment/babylon-game-server 2567:2567 &
+curl -s http://localhost:2567/game-server/ready
+```
+
+#### Before you expose it: the pod public address
+
+`deployment.yaml` sets `GAME_SERVER_PUBLIC_ADDRESS` to the pod IP. Once a public address is set, **every** seat
+reservation sends the browser to it (`wss://<pod IP>:2567` when the game uses `wss://`), so it only works when players
+can reach pod IPs directly with a valid certificate, which is rare. Choose:
+
+- **One replica behind a TLS Ingress (the common case):** remove the `GAME_SERVER_PUBLIC_ADDRESS` entry (and, if you
+  like, `GAME_SERVER_REDIS_URL` and `redis.yaml`). Seat reservations then use the address the game already connected to.
+- **Several replicas:** give each pod its own address players can reach, with TLS valid for it, and set
+  `GAME_SERVER_PUBLIC_ADDRESS` to it, for example a StatefulSet with one LoadBalancer Service and DNS name per pod
+  (`game-0.example.com`), or `hostNetwork` nodes with public IPs. Keep the shared Redis.
+
+#### WebSocket through an Ingress
+
+Add `GAME_SERVER_TRUST_PROXY: "true"` to the Deployment (the Ingress controller forwards the player's address; the
+template does not set it, so without it every player shares the controller's address for the join-rate limit). An
+example Ingress for ingress-nginx (not shipped with the package):
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: babylon-game-server
+  annotations:
+    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
+    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
+spec:
+  ingressClassName: nginx
+  tls:
+    - hosts: [game.example.com]
+      secretName: game-example-com-tls        # for example from cert-manager
+  rules:
+    - host: game.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: babylon-game-server
+                port:
+                  number: 2567
+```
+
+#### Secrets and settings
+
+```sh
+kubectl create secret generic babylon-game-server \
+  --from-literal=GAME_SERVER_ADMIN_TOKEN="$(openssl rand -hex 32)" \
+  --from-literal=GAME_SERVER_AUTH_JWT_SECRET="..."
+```
+
+```yaml
+          env:
+            - name: GAME_SERVER_ALLOWED_ORIGINS
+              value: https://game.example.com
+            - name: GAME_SERVER_AUTH_ENABLED
+              value: "true"
+            - name: GAME_SERVER_AUTH_MODE
+              value: jwt
+            - name: GAME_SERVER_ADMIN_TOKEN
+              valueFrom:
+                secretKeyRef: { name: babylon-game-server, key: GAME_SERVER_ADMIN_TOKEN }
+            - name: GAME_SERVER_AUTH_JWT_SECRET
+              valueFrom:
+                secretKeyRef: { name: babylon-game-server, key: GAME_SERVER_AUTH_JWT_SECRET }
+```
+
+A config file can be mounted from a ConfigMap and named with `GAME_SERVER_CONFIG` (needed for dedicated scenes).
+
+#### Server TLS and UDP
+
+Mount the certificate from a TLS Secret (cert-manager can keep it renewed; the mounted files update and the server
+reloads them within 30 seconds, HTTP/3 after a restart):
+
+```yaml
+          env:
+            - name: GAME_SERVER_TLS_ENABLED
+              value: "true"
+            - name: GAME_SERVER_TLS_CERT_FILE
+              value: /certs/tls.crt
+            - name: GAME_SERVER_TLS_KEY_FILE
+              value: /certs/tls.key
+            - name: GAME_SERVER_UDP_ENABLED
+              value: "true"
+          ports:
+            - { name: game, containerPort: 2567, protocol: TCP }
+            - { name: game-udp, containerPort: 2567, protocol: UDP }
+          volumeMounts:
+            - { name: certs, mountPath: /certs, readOnly: true }
+          livenessProbe:
+            httpGet: { path: /game-server/health, port: game, scheme: HTTPS }
+          readinessProbe:
+            httpGet: { path: /game-server/ready, port: game, scheme: HTTPS }
+      volumes:
+        - name: certs
+          secret: { secretName: game-example-com-tls }
+```
+
+With server TLS the probes must use `scheme: HTTPS` (the kubelet does not verify the certificate). Expose TCP and UDP on
+the same port with a LoadBalancer Service (example, not shipped; mixed-protocol LoadBalancers need a cluster and cloud
+provider that support them):
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: babylon-game-server-public
+spec:
+  type: LoadBalancer
+  externalTrafficPolicy: Local          # keeps the player's address (no proxy header on this path)
+  selector:
+    app: babylon-game-server
+  ports:
+    - { name: wss, port: 443, targetPort: 2567, protocol: TCP }
+    - { name: h3,  port: 443, targetPort: 2567, protocol: UDP }
+```
+
+Players use `wss://game.example.com` (DNS to the Service's external address); TCP 443 and UDP 443 both reach the pod.
+Leave `GAME_SERVER_TRUST_PROXY` off on this path.
+
+#### Probes and rolling updates
+
+- Liveness `/game-server/health` restarts a stuck process; readiness `/game-server/ready` removes a draining pod or one
+  that lost Redis from the Service.
+- A rolling update with one replica starts the new pod before stopping the old one (the default `maxSurge` rounds up to
+  1). The old pod gets `SIGTERM`, drains for up to 30 s, and is killed after `terminationGracePeriodSeconds: 45`.
+
+### 4.6 Fly.io
+
+`fly.toml`. **TLS:** edge (Fly's proxy on 443). **UDP:** no. **Scaling:** one machine.
+
+The template builds the init `Dockerfile`, sets `GAME_SERVER_PORT = "2567"` and `GAME_SERVER_TRUST_PROXY = "true"`, serves
+443 (TLS + HTTP) and 80 (redirect to HTTPS), keeps one machine running (`auto_stop_machines = "off"`,
+`min_machines_running = 1`), checks `/game-server/ready` every 15 s, and waits `kill_timeout = "45s"` on stop.
+
+```sh
+fly launch --copy-config --no-deploy        # pick an app name; it replaces "app" in fly.toml
+fly secrets set GAME_SERVER_ADMIN_TOKEN="$(openssl rand -hex 32)" \
+  GAME_SERVER_AUTH_ENABLED=true GAME_SERVER_AUTH_MODE=shared-secret GAME_SERVER_AUTH_SHARED_SECRET_TOKENS=...
+fly deploy
+curl -s https://<app>.fly.dev/game-server/ready
+```
+
+Players use `wss://<app>.fly.dev`, or your domain after `fly certs add game.example.com`. Put non-secret settings
+(`GAME_SERVER_ALLOWED_ORIGINS`) in the `[env]` section.
+
+**Why no UDP:** Fly delivers UDP only to a socket bound to the special address `fly-global-services`, while the server's
+HTTP/3 transport binds one address for TCP and UDP together. **Why one machine:** Fly machines share the app's public
+address, so they have no individual address for seat reservations. To scale, run separate Fly apps (each with its own
+host name as `GAME_SERVER_PUBLIC_ADDRESS`) sharing one external Redis.
+
+### 4.7 Railway
+
+`railway.json`. **TLS:** edge. **UDP:** no (Railway has no inbound UDP). **Scaling:** `numReplicas: 1`.
+
+Railway builds the `Dockerfile`, sets `PORT` (which the server honours), uses `/game-server/ready` as the deployment
+health check (`healthcheckTimeout: 60`), and restarts on failure. JSON has no comments, so the recipe's header lives in
+the starter `DEPLOY.md`.
+
+```sh
+railway init
+railway up
+railway domain        # players use wss://<generated domain>
+```
+
+Set `GAME_SERVER_TRUST_PROXY=true` and your production settings in the service's variables (secrets as sealed
+variables). Do not set `GAME_SERVER_PORT`. Keep one replica: replicas share the service's domain, so they have no
+individual address for seat reservations.
+
+### 4.8 Render
+
+`render.yaml`. **TLS:** edge. **UDP:** no (HTTP and WebSocket only). **Scaling:** `numInstances: 1`.
+
+A Docker web service (`plan: starter`) with `healthCheckPath: /game-server/ready` and `GAME_SERVER_TRUST_PROXY=true`.
+Render sets `PORT`, which the server honours.
+
+1. Commit the starter folder to a repository.
+2. In the Render dashboard: **New > Blueprint**, pick the repository.
+3. Add your settings under `envVars` in `render.yaml` (secrets with `sync: false`, then set the value in the dashboard).
+
+Players use `wss://<service>.onrender.com` or your custom domain. Keep one instance (instances share one host name).
+
+### 4.9 DigitalOcean App Platform
+
+`digitalocean-app.yaml`. **TLS:** edge. **UDP:** no (HTTP only). **Scaling:** `instance_count: 1`.
+
+A service built from the `Dockerfile` (`instance_size_slug: apps-s-1vcpu-1gb`, `http_port: 2567`), health check
+`/game-server/ready` (`initial_delay_seconds: 20`, `period_seconds: 15`), with `GAME_SERVER_PORT=2567` and
+`GAME_SERVER_TRUST_PROXY=true`.
+
+1. Commit the starter folder to a GitHub repository and set `github.repo` (and `branch`) in the file.
+2. Add your settings under `envs` (secrets with `type: SECRET`).
+3. Create the app:
+
+```sh
+doctl apps create --spec digitalocean-app.yaml
+# later changes:
+doctl apps update <app id> --spec digitalocean-app.yaml
+```
+
+Players use `wss://<app>.ondigitalocean.app` or your custom domain. With `deploy_on_push: true`, every push to the branch
+redeploys. Keep one instance.
+
+### 4.10 Heroku
+
+`heroku.yml` + `app.json`. **TLS:** edge (Heroku router). **UDP:** no (HTTP routing only). **Scaling:** one dyno.
+
+The container stack builds the `Dockerfile`. `app.json` sets the stack, `GAME_SERVER_TRUST_PROXY=true`, and
+`GAME_SERVER_DRAIN_SECONDS=25`, because Heroku stops a dyno 30 seconds after `SIGTERM`. Heroku sets `PORT`.
+
+```sh
+heroku create --stack container
+heroku config:set GAME_SERVER_ALLOWED_ORIGINS=https://game.example.com \
+  GAME_SERVER_ADMIN_TOKEN="$(openssl rand -hex 32)" \
+  GAME_SERVER_AUTH_ENABLED=true GAME_SERVER_AUTH_MODE=jwt GAME_SERVER_AUTH_JWT_SECRET=...
+git push heroku main
+```
+
+`app.json` also describes a Deploy-to-Heroku button (formation `web`, size `basic`). Players use
+`wss://<app>.herokuapp.com`. Keep one dyno: dynos share the app's host name.
+
+### 4.11 Colyseus Cloud
+
+`colyseus-cloud/`. **TLS:** edge (Colyseus Cloud's NGINX serves `wss://`). **UDP:** no. **Scaling:** one process per CPU,
+sharing Redis, behind one address.
+
+This is the recommended host. Colyseus Cloud deploys only from git: it clones a branch, runs `npm install` and the
+`build` script, then starts the processes with PM2. The folder is a small deploy repository that installs the published
+package, with a no-op build. Push it as a repository of its own, or keep it as a subfolder of another repository (your
+game's) and set the application's **Root directory** and watch paths to it on the panel. Do not point Colyseus Cloud at
+this package's own source folder: every push to it would deploy, each deploy would run the TypeScript and console build,
+and the source repository does not commit `package-lock.json`. The steps below add to the folder's own `README.md`.
+
+**Publish first.** The recipe installs `@babylonjs-toolkit/server` from npm, so that version must be published:
+
+```sh
+cd SVR && npm run release:publish
+# then, in the folder init wrote:
+cd colyseus-cloud && npm install
+git add package.json package-lock.json
+```
+
+Commit `package-lock.json` with every change to `package.json`. Installing is Colyseus Cloud's own build step, before
+`colyseus-post-deploy` runs. The `@colyseus/tools` deploy scripts and the `@colyseus/cloud` command never install
+anything or read a lockfile, and the Cloud documentation does not say which install command it runs, only that a pnpm
+project must push `pnpm-lock.yaml` so that Cloud can install it. Both `npm install` and `npm ci` follow a lockfile that
+matches `package.json`, and `npm ci` stops with an error when the two disagree. The rehearsal itself runs `npm install`;
+`npm ci` passed separately on a generated lockfile with a fresh tarball, on macOS with `--ignore-scripts`. Do not commit `node_modules`: Colyseus's troubleshooting page lists that as a cause of "Permission
+denied" deploy failures.
+
+**First deploy checklist:**
+
+1. Confirm that the application runs Node 22 or newer. Colyseus does not document Cloud's Node version, so ask
+   Colyseus support before the first deploy. Choose the plan by memory as well as CPU:
+   Colyseus Cloud sizes each process's memory limit from the plan, about 1.1 GB per process with 2 GB per CPU but only
+   256 MB on the smallest 1 GB plan, and its machines have no swap. A WebSocket-only server for client-hosted games fits
+   the smallest plan; dedicated sessions need measuring (see below).
+2. On the panel, set `NODE_ENV=production`, `GAME_SERVER_ALLOWED_ORIGINS` (your game's web address) and
+   `GAME_SERVER_ADMIN_TOKEN` (a long random secret).
+3. Connect the repository, or run `npx @colyseus/cloud deploy` from the folder.
+4. Read the startup banner in the application logs. It must show the `wss://` address and `Redis: on` (on a plan of more
+   than one CPU):
+
+   ```text
+   Babylon Game Server <version> listening on wss://<application-address>
+     HTTP:         https://<application-address>
+     WebTransport: off
+     TLS: off   UDP: off   Auth: off   Redis: on (127.0.0.1:6379)
+   ```
+
+5. Put that address in the game's `VITE_FUSION_SERVER_URL`, and rebuild the game.
+6. Race two players from two browsers.
+7. Open the setup link from the logs, and check three things the rehearsal could only assume, because Colyseus does not
+   document which headers its NGINX forwards:
+   - The console opens. If it answers `the console needs HTTPS`, Cloud's NGINX is not sending `X-Forwarded-Proto: https`.
+   - One console change saves. The CSRF check compares `Origin` with `scheme://<Host>`, so if Cloud's NGINX rewrites
+     `Host`, sign-in works but every console change returns 403.
+   - The console's Players page shows a player's real address. The server reads `X-Real-IP`, then the first entry of
+     `X-Forwarded-For`. If the page shows one internal address for everyone, the address is not reaching the server, and
+     address bans and rate limits would catch every player at once. If NGINX keeps an `X-Forwarded-For` the player sent
+     at the front of that list, and sets no `X-Real-IP`, a player can name any address. Send a request with a made-up
+     `X-Forwarded-For` and see which address is recorded. Until you have checked this, do not rely on address bans.
+
+**What Cloud sets for you.** These apply only when `COLYSEUS_CLOUD` is set, and sit below everything else, so a config
+file value, a `GAME_SERVER_*` variable or a flag still wins:
+
+| Setting | Value on Colyseus Cloud |
+|---|---|
+| `publicUrl` | `wss://<SUBDOMAIN>.<SERVER_NAME>` |
+| `trustProxy` | `true` |
+| `drainSeconds` | `600` |
+| `redis.url` | `REDIS_URI` when set, else `redis://127.0.0.1:6379` on a machine of more than one CPU, else none |
+| `admin.dataDir` | `.babylon-game-server-data` in the home folder, used only without Redis |
+
+The config page of the admin console labels these values "Colyseus Cloud". The precedence is defaults < Colyseus Cloud's
+defaults (on this host only) < config file < environment < flags. Panel variables reach the server through `.env.cloud`,
+which Colyseus loads before the server reads its config.
+
+**What it refuses.** The server stops at startup and names the setting to change, because each of these breaks routing
+behind Cloud's NGINX:
+
+| Setting | Refusal |
+|---|---|
+| `GAME_SERVER_TLS_ENABLED` | `Colyseus Cloud serves TLS itself; turn off GAME_SERVER_TLS_ENABLED` |
+| `GAME_SERVER_UDP_ENABLED` | `UDP does not reach the server on Colyseus Cloud; turn off GAME_SERVER_UDP_ENABLED` |
+| `GAME_SERVER_PUBLIC_ADDRESS` | `Colyseus Cloud sets the public address; unset GAME_SERVER_PUBLIC_ADDRESS` |
+
+**Admin console.** The server logs one setup link per process, and any of them works, whichever process NGINX picks. Use
+one of them: the first owner ends them all. `babylon-game-server admin create-owner` needs a shell on the machine, so on
+Cloud the link is the way in. Console accounts live in Redis on a plan of more than one CPU, so they survive a deploy.
+
+**Leaderboards.** The [built-in leaderboards](README.md#leaderboards) need no extra service:
+
+- Commit the definitions file, for example `leaderboards.json`, to the deploy repository, and set
+  `leaderboards: { definitionsFile: "./leaderboards.json" }` in `babylon-game-server.config.mjs` (or
+  `GAME_SERVER_LEADERBOARDS_DEFINITIONS_FILE` on the panel). Every process creates the missing boards at start; console
+  edits are kept across deploys. A server version without leaderboards refuses the unknown `leaderboards` key and
+  stops, so set it only once the deployed version has them.
+- The scores live where the console's data does. On a plan of more than one CPU that is the machine's local Redis,
+  and Colyseus does not document whether it survives deploys and restarts; on a 1-CPU plan it is files in the home
+  folder, which a redeploy can wipe. For production, set `REDIS_URI` on the panel to an external Redis with persistence
+  (append-only file or snapshots, as a managed Redis provides). The console's Leaderboards page shows whether the
+  storage is durable, unknown or not durable, and what to change; export a backup from its Settings tab before
+  changing hosts.
+
+**Dedicated sessions.** A dedicated session runs in the server processes, so it needs no port or container of its own:
+
+- Keep each scene in the repository, with a `sceneRoot` such as `./scenes/arena/`, or at an `https://` `sceneRoot`.
+  Dedicated scenes are configured only in `babylon-game-server.config.mjs`.
+- Each process is one thread, so `instances: os.cpus().length` is what adds dedicated capacity. Choose a plan by CPU.
+- Set `limits.maxDedicatedSessions` by measurement, as in
+  [Dedicated sessions need CPU and memory](#dedicated-sessions-need-cpu-and-memory). `@colyseus/tools` works out a
+  memory limit per process from the machine's RAM. A process over it restarts, which ends every session on it.
+- A `boot` session runs once, however many processes there are: one process holds the `dedicated-boot` lease in Redis and
+  runs them.
+- **A `boot` session delays every deploy by the drain time.** It never empties, so the process holding it drains for the
+  full `drainSeconds`: 600 s by default here. The players in it then get `GameClosed`. The lease passes to a new process
+  once the old one stops renewing it, 30 s after the drain starts, but the new process waits for the old session to end
+  so that two sessions never share a name. It starts the session within about 10 s of the old one ending. Set
+  `GAME_SERVER_DRAIN_SECONDS` lower on the panel if your boot
+  session should not hold a deploy that long; the same value limits every other running session too.
+- **A bad boot scene does not fail a rolling deploy.** The new processes are not the lease holder when they first start,
+  so a scene that cannot load fails later, after the deploy has reported success, and the process stays ready. A failure
+  stops a process at startup only when it takes the lease at its first attempt, as on the very first deploy. After a
+  deploy that changes a boot scene, watch for this line, which the holder logs at `error` every 10 seconds:
+
+  ```text
+  the boot dedicated sessions could not start; trying again
+  ```
+
+  Then confirm that the session is listed: `curl -H "Authorization: Bearer $GAME_SERVER_ADMIN_TOKEN"
+  https://<application-address>/game-server/admin/sessions`.
+
+**Deploying an update.** Colyseus rolls a deploy out process by process: half the processes come up new, NGINX moves to
+them, and the old ones drain. Port numbers change between deploys, so never write one down. A joined session keeps
+running on its old process until it ends, up to `drainSeconds`, and a process with no sessions left exits at once.
+A draining process gets no new sessions: every process's matchmaker skips it, so new sessions open on the new
+processes only. A deploy whose new processes do not listen within `listen_timeout` (two minutes in the template) fails,
+and the old version keeps serving; the very first deploy is not checked that way, so read its logs for the banner.
+`npx @colyseus/cloud deploy` only asks Cloud to deploy the pushed branch and returns before the deploy finishes, even
+when it fails, so read the result on the panel. An uncaught error in a process drains it too (exit code 1), so one bad
+session does not cut off every player on that process at once.
+
+**Why the template sets `kill_timeout` and `listen_timeout`.** Colyseus Cloud's deploy agent fills in 30 minutes and
+60 s when they are unset, but when the agent is not running, deploys fall back to a plain PM2 reload with PM2's own
+defaults: a 1.6 s kill timeout, which cuts the drain off. Colyseus recorded exactly that in production in the
+`@colyseus/tools` 0.18.11 changelog. Keep `max_memory_restart` unset unless you have measured: Cloud sizes it from the
+plan.
+
+**Watching it from the admin console.** Add a Colyseus Cloud API token (`GAME_SERVER_ADMIN_COLYSEUS_CLOUD_API_TOKEN`,
+or `COLYSEUS_CLOUD_TOKEN`) on the panel and the console's **Colyseus Cloud** page shows the application's status,
+host processes, 30-day history, traffic, deploys, host logs and billing next to the server's own pages. Without a token, the page on
+Colyseus Cloud explains how to add one. See [Colyseus Cloud page](README.md#colyseus-cloud-page).
+
+**Costs and limits.** Colyseus Cloud is
+[billed monthly up front](https://docs.colyseus.io/cloud/pricing-billing), per application and location. The live
+price list behind the [pricing page](https://colyseus.io/pricing) started at $12.50/month (1 shared vCPU, 1 GB) on
+2026-11-08, with the recommended High Frequency machines from $18/month; the page's own "from $15" was out of date.
+There is no free tier, refunds are only within 7 days of the first payment, there are no player (CCU) limits and
+bandwidth is listed as unlimited. The SLA covers 99.9% network and host uptime, not application crashes; support is by
+email. Stopping a process has a 30-minute limit (`kill_timeout`), so keep `drainSeconds` below 1800.
+
+**Open questions from the docs.** Colyseus does not publish its NGINX site configuration, so which headers it forwards
+stays a first-deploy check (step 7 above). It does not document Cloud's Node version, the install command its build
+runs (`npm ci` or `npm install`; commit the lockfile so both work), whether the machine's local Redis keeps its data
+across deploys and restarts (it holds the console accounts on plans of more than one CPU), or custom domains beyond a
+2023 announcement for Cloudflare-managed DNS. Check them with Colyseus support before you depend on them.
+
+---
+
+## 5. Serving dedicated-session scenes
+
+A dedicated session runs a headless `TOOLKIT.NetworkRunner` in **Server** mode: it loads the same exported scene the
+browsers load and simulates everything. Players join with `GameMode.Client` and the session name. Dedicated scenes are
+configured only in the config file:
+
+```js
+// babylon-game-server.config.mjs
+export default {
+    dedicated: {
+        scenes: [
+            { name: "arena", sceneRoot: "/app/scenes/arena/", sceneFile: "arena.gltf", projectScripts: [], maxPlayers: 8, onDemand: true, idleSeconds: 60 }
+        ],
+        boot: [
+            { sessionName: "arena-1", sceneName: "arena" }
+        ]
+    }
+};
+```
+
+| Field | Meaning | Default |
+|---|---|---|
+| `name` | The name clients and the admin API use | required |
+| `sceneRoot` | An `http(s)://` URL, or a folder on the server, holding the exported scene | required |
+| `sceneFile` | The exported scene file in that folder | required |
+| `projectScripts` | Extra script bundles (URLs or paths) loaded before the scene | `[]` |
+| `maxPlayers` | Most players | `8` |
+| `onDemand` | A `Client` join naming this scene may start it | `false` |
+| `idleSeconds` | Seconds an on-demand session stays up after its last player left (after the reconnect grace period) | `60` |
+
+Sessions start three ways: each `boot` entry with the server (it never closes); `POST /game-server/admin/dedicated`; or
+on demand, when a `Client` join's session property `dedicatedScene` names a scene with `onDemand: true`. At most
+`limits.maxDedicatedSessions` run at once per instance.
+
+### Where the scene comes from
+
+**A folder (recommended for production).** Mount or copy the exported scene folder (the scene file, its buffers, and the
+project script bundle the exporter writes next to it, which loads automatically) into the container, readable by the
+`node` user. Relative paths resolve against the server's working directory (`/app` in the image); prefer absolute paths.
+
+```sh
+# Mount at run time:
+docker run -d -p 2567:2567 \
+  -v /srv/game/export/scenes:/app/scenes/arena:ro \
+  -v "$PWD/babylon-game-server.config.mjs:/app/config/babylon-game-server.config.mjs:ro" \
+  -e GAME_SERVER_CONFIG=/app/config/babylon-game-server.config.mjs \
+  ghcr.io/mackeyk24/babylon-game-server:<version>
+```
+
+Or bake it into your image by uncommenting the line in the init `Dockerfile`:
+
+```dockerfile
+COPY scenes/ /app/scenes/
+```
+
+Baking the scene in ties a server image to a game build, which keeps the two in step and makes rollbacks exact.
+
+**A URL.** `sceneRoot: "https://game.example.com/scenes/"` makes the server fetch the scene over HTTP(S) when each
+session starts. The server needs outbound access to that host. A running session keeps the scene it loaded; new sessions
+fetch the current files.
+
+**Only configured locations load.** The headless runtime fetches only from the configured `sceneRoot` and
+`projectScripts` locations; a client can name a scene, never a URL. Anything the scene needs must live under its root.
+
+### Keeping the server and the game in step
+
+The dedicated runner and the browsers must run the same export. After you re-export a game, restart its dedicated
+sessions (redeploy, or close them with the admin API and start them again); a mismatch shows as
+`IncompatibleConfiguration` with no detail (different prefab tables). The game's script bundle must register its input
+struct with `TOOLKIT.NetworkRunner.setDefaultInputDefinition(...)`, because no launcher starts the dedicated runner.
+
+### Sizing
+
+Each dedicated session runs a full scene simulation on the instance's one JavaScript thread. Measure with the dedicated
+metrics, set `GAME_SERVER_MAX_DEDICATED_SESSIONS` to what one instance sustains, and add instances rather than CPU. See
+[Dedicated sessions need CPU and memory](#dedicated-sessions-need-cpu-and-memory). Raise the memory limit when you load
+large scenes.
+
+A boot session that fails to load stops the server at startup (exit code 1), so a wrong `sceneRoot` shows up at deploy
+time. An on-demand or admin-started session that fails answers `GameNotFound: the dedicated scene <name> failed to load`
+or 503 from the admin API, and the log says why.
+
+---
+
+## 6. Operating it
+
+### Health and readiness
+
+```sh
+curl -s https://game.example.com/game-server/health    # {"status":"ok"}
+curl -s https://game.example.com/game-server/ready     # {"ready":true} or 503 {"ready":false,"reasons":["draining"]}
+curl -s https://game.example.com/game-server/info      # version, protocol version, transports, authRequired
+```
+
+`/game-server/info` is also how you confirm UDP: `transports.webTransport` is `{ port, certificateHash }` when UDP is on,
+`null` when off (`certificateHash` is non-null only with a pinned development certificate).
+
+### Metrics
+
+`GET /metrics` serves Prometheus text, every metric prefixed `babylon_game_server_`:
+
+| Metric | Type | Labels |
+|---|---|---|
+| `babylon_game_server_players` | gauge | `game_mode` |
+| `babylon_game_server_sessions` | gauge | `game_mode` |
+| `babylon_game_server_dedicated_sessions` | gauge | |
+| `babylon_game_server_joins_total` | counter | `result` |
+| `babylon_game_server_refusals_total` | counter | `reason` |
+| `babylon_game_server_auth_failures_total` | counter | `mode` |
+| `babylon_game_server_frames_total` | counter | `direction`, `transport`, `channel` |
+| `babylon_game_server_bytes_total` | counter | `direction`, `transport` |
+| `babylon_game_server_dedicated_tick_overruns_total` | counter | |
+| `babylon_game_server_dedicated_frame_seconds` | histogram | |
+
+The Node.js process metrics (CPU, memory, event-loop lag, garbage collection) carry the same prefix. Each instance
+reports only itself, so scrape every instance on its own address, not through the load balancer.
+
+Prometheus scrape configuration (with `metrics.requireAdminToken` on):
+
+```yaml
+scrape_configs:
+  - job_name: babylon-game-server
+    metrics_path: /metrics
+    scheme: http                     # https when TLS is on the server
+    authorization:
+      credentials_file: /etc/prometheus/game-server-admin-token
+    static_configs:
+      - targets: ["10.0.1.12:2567", "10.0.2.31:2567"]
+```
+
+On Kubernetes with the Prometheus Operator, a PodMonitor (example):
+
+```yaml
+apiVersion: monitoring.coreos.com/v1
+kind: PodMonitor
+metadata:
+  name: babylon-game-server
+spec:
+  selector:
+    matchLabels:
+      app: babylon-game-server
+  podMetricsEndpoints:
+    - port: game
+      path: /metrics
+```
+
+Useful queries for a Grafana dashboard:
+
+```promql
+sum(babylon_game_server_players)                                          # players online
+sum by (game_mode) (babylon_game_server_sessions)                         # sessions by mode
+sum by (reason) (rate(babylon_game_server_refusals_total[5m]))            # why joins fail
+sum by (transport) (rate(babylon_game_server_frames_total{direction="in"}[5m]))   # WebSocket vs WebTransport traffic
+histogram_quantile(0.99, sum by (le) (rate(babylon_game_server_dedicated_frame_seconds_bucket[5m])))
+rate(babylon_game_server_dedicated_tick_overruns_total[5m])               # dedicated sessions falling behind
+```
+
+On AWS, Amazon Managed Service for Prometheus can store these: run a collector (for example the AWS Distro for
+OpenTelemetry collector or a Prometheus agent) that scrapes each task's private address and remote-writes to the
+workspace, and use Amazon Managed Grafana with that workspace as its data source.
+
+Suggested alerts: readiness failing for more than a few minutes; a rising `refusals_total` for `MaxCcuReached`;
+`dedicated_tick_overruns_total` increasing steadily; event-loop lag above your tick time.
+
+### Logs
+
+Production logs are JSON lines to stdout (info, debug) and stderr (warn, error). Every platform recipe collects them:
+CloudWatch Logs on ECS, `kubectl logs`, `fly logs`, `heroku logs --tail`, the Railway / Render / DigitalOcean log views,
+`docker logs` and `journalctl` on a VM. Messages worth watching:
+
+| Message | Meaning |
+|---|---|
+| `join refused` | A join was refused; the reason and `clientAddress` are in the fields |
+| `auth is disabled and the server listens on ...` | Production with auth off (a warning at startup) |
+| `draining` / `waiting for sessions to end` / `drained` | A drain started, is waiting, finished |
+| `drain did not finish in time` | The drain watchdog exited the process with code 1 |
+| `certificate reloaded` | Renewed certificate files were applied |
+| `HTTP/3 uses the new certificate after a restart` | Renewed with UDP on: restart when convenient |
+| `certificate reload failed` | A half-written renewal; retried at the next 30 s poll |
+| `token verifier failed` | Your webhook or custom verifier threw |
+| `the dedicated session did not start` | An admin-started dedicated session failed; the error is in the fields |
+
+Tokens, secrets and keys are never logged.
+
+### The admin API
+
+Available only when `GAME_SERVER_ADMIN_TOKEN` is set (404 otherwise; 401 with a wrong token).
+
+```sh
+GS=https://game.example.com
+TOKEN=...                                         # GAME_SERVER_ADMIN_TOKEN
+
+# List every session (every instance when scaled out with Redis)
+curl -s -H "Authorization: Bearer $TOKEN" $GS/game-server/admin/sessions
+# [{"roomId":"abc123","sessionName":"arena","gameMode":"Shared","players":4,"maxPlayers":8,"isDedicated":false}]
+
+# Disconnect a session's players (200 {"closed":"abc123"}, 404 if unknown)
+curl -s -X POST -H "Authorization: Bearer $TOKEN" $GS/game-server/admin/sessions/abc123/close
+
+# Start a dedicated session of a configured scene (201 {"roomId":...}; 400, 404 unknown scene, 503 did not start)
+curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"sceneName":"arena","sessionName":"arena-2"}' $GS/game-server/admin/dedicated
+
+# Start a drain without exiting the process (202 {"draining":true})
+curl -s -X POST -H "Authorization: Bearer $TOKEN" $GS/game-server/admin/drain
+```
+
+When scaled out, the session list and close work across instances, but **dedicated** and **drain** act on the instance
+that receives the call: call that instance's own address.
+
+After an admin drain finishes, the server stops listening while the process keeps running, so health checks fail. Most
+orchestrators then restart it; on plain Docker or systemd, restart it yourself. Use it to empty an instance before
+maintenance.
+
+### Rolling updates and draining
+
+On `SIGTERM` (every platform's stop signal), the server:
+
+1. Stops taking joins at once: readiness turns 503 and new joins are refused with `GameClosed: the server is shutting
+   down` (a game that joins again reaches another instance).
+2. Lets running sessions continue until they end or `drainSeconds` passes (the drain ends early when no sessions are
+   left).
+3. Tells the remaining players `GameClosed` and disconnects them.
+4. Exits 0 (or 1 if the watchdog at `drainSeconds` + 5 s fires first).
+
+Sessions never move between instances, so a deploy ends any session still running on the old instance when its drain
+ends. To roll out with the least disruption:
+
+- Start new instances before stopping old ones. ECS (default deployment settings) and Kubernetes (default rolling
+  update) do; on the other platforms, check how a deploy replaces running instances.
+- Give the stop timeout more than `drainSeconds` + 5 s ([checklist item 9](#9-stop-timeout-vs-drainseconds)).
+- Deploy when few sessions are running, or raise `drainSeconds` (within the platform's limit) so matches can finish.
+- Without Redis, players who join during the overlap land on the new instance while old sessions finish on the old one.
+- On ECS, the load balancer deregisters a task before the task receives `SIGTERM` (the templates set the deregistration
+  delay to 45 s). Test a rolling deploy with a live session and confirm the players see the drain as you expect before
+  relying on it.
+- When a release changes the protocol version, the old game pages are refused by the new server. Deploy the server and
+  the game together, or keep the old server on its own address until players have reloaded.
+
+### Certificate renewal
+
+| How the certificate is supplied | Renewal |
+|---|---|
+| At the edge (Caddy, ALB/ACM, platforms, Ingress with cert-manager) | Automatic; nothing to do on the server |
+| `tls.certFile` / `tls.keyFile` | Replace the files; they are polled every 30 s and applied to HTTPS and WSS without a restart |
+| `tls.certPem` / `tls.keyPem` (environment, Secrets Manager) | Read at start: update the secret and restart (ECS: `aws ecs update-service --force-new-deployment`) |
+| Any source, with UDP on | HTTP/3 keeps its certificate until the next restart: restart after renewal |
+
+Let's Encrypt certificates last 90 days and certbot renews them well before expiry; with UDP on, restart from the
+certbot deploy hook (as in [Certificates with certbot](#certificates-with-certbot)) so HTTP/3 never serves an expired
+certificate.
+
+### Backups
+
+None needed. The server is stateless: sessions live in memory and end when the process stops. Redis holds only
+short-lived session listings and seat reservations (the shipped Redis runs without persistence). Keep in version control
+or your secret store what you need to rebuild: the config file, the environment and secrets, your image tag, and the
+exported scenes for dedicated sessions.
+
+---
+
+## 7. Connecting the game
+
+The game points its `NetworkRunner` at the server URL and, when the server requires it, passes a token.
+
+```ts
+const runner: TOOLKIT.NetworkRunner = new TOOLKIT.NetworkRunner(scene);
+const result: TOOLKIT.StartGameResult = await runner.startGame({
+    gameMode: TOOLKIT.GameMode.AutoHostOrClient,
+    sessionName: "arena",
+    config: { serverUrl: "wss://game.example.com" },
+    authToken: playerToken,                                        // only when the server enables auth
+    transportPreference: TOOLKIT.NetworkTransportPreference.Auto   // the default
+});
+if (!result.ok) console.error(TOOLKIT.ShutdownReason[result.shutdownReason] + " " + result.errorMessage);
+```
+
+- **`serverUrl`**: the public URL, authored on the scene's `NetworkSettings` component or passed in `config`. Use
+  `wss://` whenever the page is served over `https://`; browsers block `ws://` there. With TLS at the edge it is the
+  edge's address (`wss://<app>.fly.dev`, `wss://game.example.com`), never the container's internal port.
+- **`authToken`**: sent with every matchmaking call, the session lobby included. With auth off the server ignores it.
+  The host's `onConnectRequest(runner, request, token)` sees the server-verified identity as `request.authIdentity`.
+- **`transportPreference`**: `Auto` (WebTransport when the server offers it, the browser has it and a quick probe
+  succeeds, else WebSocket), `WebSocket`, or `WebTransport` (refused with `ConnectionRefused` when it cannot be used).
+  Keep `Auto` in production.
+- **Origins:** the page's origin must be in `GAME_SERVER_ALLOWED_ORIGINS` when that list is set; the game reads
+  `/game-server/info` before joining, and CORS applies to it.
+- **Pages from the exporter (UMD)** need the exporter's **Babylon Toolkit Networking** option on, so the page loads the
+  Colyseus browser client (`scripts/colyseus.js`). **ESM web apps** install `@colyseus/sdk@0.18.5` and set
+  `ColyseusTransport.ClientModule = await import("@colyseus/sdk")` before the first `startGame`.
+- **Dedicated sessions:** join with `GameMode.Client` and the session name; to start an on-demand scene, pass
+  `sessionProperties: { dedicatedScene: "arena" }`.
+
+The toolkit's sample launcher reads the same settings from the page URL, which is handy for testing a deployment
+(the parameter names are the launcher's wire names):
+
+```text
+engine.html?scene=networktestbed.gltf&fusionMode=Shared&fusionSession=race1&fusionServer=wss%3A%2F%2Fgame.example.com&fusionToken=abc&fusionStats=1
+```
+
+| Parameter | Meaning |
+|---|---|
+| `fusionServer` | The server URL, URL-encoded |
+| `fusionToken` | The auth token |
+| `fusionTransport` | `auto`, `websocket` or `webtransport` |
+| `fusionDedicatedScene` | With `fusionMode=Client`: an on-demand dedicated scene |
+| `fusionStats` | `1` shows the network stats overlay, which names the active link (WebSocket or WebTransport) |
+
+---
+
+## 8. Troubleshooting deployment
+
+Refusals reach the game as a failed `startGame` with the message `"<ShutdownReason>: <detail>"`, and are logged by the
+server as `join refused` with the same reason. The [README](README.md#troubleshooting) lists every game-side message;
+these are the ones deployment causes.
+
+### The server does not start or stay up
+
+| Symptom | Cause and fix |
+|---|---|
+| `Babylon Game Server configuration problems:` and exit code 2 | Each line names the option, its variable and what it needs (for example `tls.enabled (GAME_SERVER_TLS_ENABLED) needs a certificate: ...`, `udp.enabled (GAME_SERVER_UDP_ENABLED) needs tls.enabled (GAME_SERVER_TLS_ENABLED): ...`, `unknown option ...`). Fix them all and redeploy; restarting will not help. |
+| `the config file ... does not exist (--config / GAME_SERVER_CONFIG)` | The mounted path differs from `GAME_SERVER_CONFIG`. Check the volume mount and the file name. |
+| `tls.developmentCertificate (GAME_SERVER_TLS_DEVELOPMENT_CERTIFICATE) is refused when NODE_ENV=production` | Development certificates are for local use; supply a real certificate. |
+| `UDP needs @colyseus/h3-transport, which is not installed on this platform` | The optional native package did not build. Use the Docker image, reinstall where it builds, or run without UDP. |
+| `babylonjs-toolkit <version> is older than this server needs; ...` | The installed runtime predates the server's protocol: install the `babylonjs-toolkit` version this server was released with (`npm install @babylonjs-toolkit/server@<version>` pins it). |
+| `EACCES` reading the certificate or key | The container runs as `node` (uid 1000): make the files readable by it. |
+| `EACCES` / `permission denied` binding port 443 (systemd, Kubernetes) | Non-root processes cannot bind ports below 1024 there. Use `AmbientCapabilities=CAP_NET_BIND_SERVICE` (systemd), or listen on 2567 and map 443 → 2567 at the Service or load balancer. |
+| Container restarts; the logs show no `listening on` banner; `SIGTERM` exits at once with code 143 | **Redis credentials or address are wrong.** With wrong Redis credentials the server never starts listening, health checks fail, and because the drain handlers are installed only after it listens, `SIGTERM` ends it immediately (exit 143) with no drain log. Check `GAME_SERVER_REDIS_URL` (password, `rediss://` when the cache requires TLS, host and port), and the security group / network policy from the server to Redis. |
+| The server exits 1 right after starting, with dedicated `boot` entries | A boot dedicated session failed to load; the log names the error (wrong `sceneRoot`, missing file, script error). |
+| Docker reports the container unhealthy, but the server works | The port or TLS setting was passed as a start flag, which the image's `HEALTHCHECK` does not see. Use environment variables or the config file. |
+
+### Players cannot connect or are refused
+
+| Symptom | Cause and fix |
+|---|---|
+| The browser blocks the connection (mixed content) | The page is `https://` and `serverUrl` is `ws://`: use `wss://`. |
+| `ConnectionRefused: the origin <origin> is not allowed` | Add the page's exact origin (scheme, host, port) to `GAME_SERVER_ALLOWED_ORIGINS`. `(none)` means a client sent no `Origin` while `GAME_SERVER_ALLOW_MISSING_ORIGIN` is `false`. |
+| `ConnectionRefused: too many join requests from this address; try again in a minute` for many players at once | Every player appears with the proxy's address. Behind an HTTP proxy (Caddy, ALB, Ingress, PaaS), set `GAME_SERVER_TRUST_PROXY=true`. Behind a TCP/UDP load balancer (NLB, LoadBalancer Service), preserve the client IP there (`externalTrafficPolicy: Local`, target group client IP preservation) or raise `GAME_SERVER_JOIN_REQUESTS_PER_MINUTE`. |
+| Matchmaking succeeds, then the connection fails (players time out after the seat reservation) | `GAME_SERVER_PUBLIC_ADDRESS` is set to an address players cannot reach with the game's scheme, such as the pod IP from `kubernetes/deployment.yaml` behind a TLS Ingress. Remove it on a single instance, or give each instance a reachable TLS host name. |
+| `GameNotFound` for `Client` joins, or players of one match land in different sessions, with several instances | The instances do not share Redis, or one lacks its public address. Set the same `GAME_SERVER_REDIS_URL` and a reachable `GAME_SERVER_PUBLIC_ADDRESS` on every instance. |
+| Readiness 503 with `"redis unreachable"` | Redis did not answer within 1 second. Check Redis health, the network path and credentials. Every instance on that Redis leaves rotation together, by design: matchmaking cannot work without it. |
+| Readiness 503 with `"draining"` | The instance received `SIGTERM` or an admin drain. Expected during deploys; if it persists, the platform is not replacing it. |
+| `GameClosed: the server is shutting down` | The instance is draining; join again to reach another instance. |
+| `MaxCcuReached: this server is hosting its most sessions` / `... running its most dedicated sessions` | Over `GAME_SERVER_MAX_SESSIONS` / `GAME_SERVER_MAX_DEDICATED_SESSIONS`: add instances or raise the limit. |
+| `InvalidAuthentication: the identity provider's keys could not be loaded` | The server cannot reach `GAME_SERVER_AUTH_JWT_JWKS_URL`: allow outbound HTTPS (NAT gateway, egress policy). |
+| `CustomAuthenticationFailed: the auth webhook did not approve the player` | The webhook answered non-2xx, not a JSON object, or later than `GAME_SERVER_AUTH_WEBHOOK_TIMEOUT_MS`. Check its logs and its network latency from the server. |
+| `InvalidAuthentication: no token was sent` | Auth is on and the game sent no token: pass `startGame({ authToken })`. |
+
+### Connections drop or UDP is not used
+
+| Symptom | Cause and fix |
+|---|---|
+| WebSockets drop after a fixed time (60 s, 100 s, ...) | A proxy in the path has an idle timeout. The server pings every WebSocket every 10 seconds, which keeps most proxies from treating it as idle; if drops persist, raise the proxy's timeout as the templates do (ALB `idle_timeout.timeout_seconds` 3600; nginx `proxy_read_timeout`; ingress-nginx `proxy-read-timeout`) and check that the proxy passes WebSocket upgrades. |
+| Players are all on WebSocket though UDP is on (`fusionStats=1` shows WebSocket; `frames_total{transport="webtransport"}` stays at 0) | Check `GET /game-server/info`: `transports.webTransport` must not be `null`. Then check that UDP reaches the server on the **same port number as the `wss://` URL** at every layer (security group, firewall, load balancer listener, `-p 443:443/udp`), that TLS ends on the server (an edge proxy cannot carry it), and that the browser supports WebTransport. A corporate network may block UDP; those players correctly fall back to WebSocket. |
+| `ConnectionRefused: the game server does not offer WebTransport, or this browser cannot reach it` | The game forces `transportPreference: WebTransport`. Use `Auto`. |
+| `HTTP/3 uses the new certificate after a restart` and WebTransport fails after a renewal | Restart the server so HTTP/3 loads the renewed certificate. |
+
+### Version problems
+
+| Symptom | Cause and fix |
+|---|---|
+| `IncompatibleConfiguration: this server speaks network protocol <n> but the game sent <m>; update the ...` (or the game's `... the game server speaks network protocol ...`) | The server and the game's runtime differ in protocol version. Update the side the message names; when a release changes the protocol, deploy the server and the game together. |
+| `IncompatibleConfiguration` with no detail | Peers have different prefab tables: re-export, reload every page and restart dedicated sessions. |
+| Some players work, others get `IncompatibleConfiguration` during a deploy | Mixed versions: old pages cached in browsers, or old and new server instances side by side across a protocol change. Finish the rollout, have players reload, and avoid rolling a protocol change across instances that share Redis. |
+
+---
+
+## Known limitations
+
+- **The cloud recipes have not been deployed to a real account.** The AWS, Fly.io, Railway, Render, DigitalOcean,
+  Heroku and Kubernetes recipes were parsed and tested, but none was deployed to a real cloud account. Try yours on a
+  staging account before relying on it, especially the AWS NLB `TCP_QUIC` recipe.
+- **The Colyseus Cloud recipe was rehearsed, not deployed.** It ran in a local Linux container with Colyseus's own deploy
+  scripts (`colyseus-post-deploy` and the `@colyseus/tools` agent), PM2, NGINX on unix sockets and Redis, on plain HTTP and
+  Node 22, but never on a real Colyseus Cloud account. The NGINX there is a copy, so the forwarded headers are assumed:
+  see the [first deploy checklist](#411-colyseus-cloud).
+- **QUIC on a Network Load Balancer is a newer AWS feature.** Check the current Elastic Load Balancing documentation
+  for QUIC listener and target support in your region before depending on `aws/ecs-fargate-nlb-quic.yml`, and confirm
+  that players keep their own client addresses through it.
+- **A session lives in one process.** Sessions do not move between instances. A deploy, a crash or a drain ends the
+  sessions on that instance (after `drainSeconds` for a drain).
+- **Scale-out needs one public address per instance.** A single load balancer or platform host name in front of
+  several instances does not work on its own; the PaaS recipes and the AWS templates therefore run one instance each.
+  Colyseus Cloud is the exception: its NGINX gives each process its own `/<port>/` path on one host name.
+- **Boot dedicated sessions need Redis to run once.** On any host that numbers its processes (PM2 sets
+  `NODE_APP_INSTANCE`, on Colyseus Cloud or on your own VM), a `boot` session belongs to the holder of the
+  `dedicated-boot` lease. Without Redis there is no shared store, so each process holds its own lease and starts its own
+  copy.
+- **No UDP on platform edges.** Fly.io, Railway, Render, DigitalOcean App Platform, Heroku, Colyseus Cloud, ALBs and HTTP Ingresses carry
+  WebSocket only.
+- **Wrong Redis credentials prevent startup without a clear message.** The server never starts listening, and `SIGTERM`
+  then exits with code 143 instead of draining.
+- **HTTP/3 needs a restart to pick up a renewed certificate**, and PEM certificates passed as environment variables need
+  a restart for every transport.
+- **Custom auth (`custom` mode) works only from code**, through `createGameServer({ hooks: { verifyToken } })`; there is
+  no environment-only way to use it.
+- **The compose files and the `docker run` examples in the templates set no stop grace period**, so Docker's default
+  10 seconds cuts the 30-second drain unless you add `stop_grace_period` / `--stop-timeout`.