@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@babylonjs-toolkit/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "9.35.0",
+  "description": "Babylon Game Server — the multiplayer session server for Babylon Toolkit games",
+  "author": "MackeyK24 <mackeyk24@gmail.com>",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "bin": {
+    "babylon-game-server": "lib/cli.js"
+  },
+  "files": [
+    "lib",
+    "templates",
+    "README.md",
+    "DEPLOY.md",
+    "CUSTOM.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "npm run build:server && npm run build:console",
+    "build:server": "tsc -p tsconfig.json",
+    "build:console": "vite build --config console/vite.config.ts",
+    "check:console": "tsc -p console/tsconfig.json",
+    "start": "node lib/cli.js",
+    "test": "npm run build && node scripts/run-server-tests.mjs",
+    "prepack": "npm run build && node scripts/release-manifest.mjs apply",
+    "postpack": "node scripts/release-manifest.mjs restore",
+    "release:publish": "npm publish --access public",
+    "release:image": "cd .. && docker buildx build --platform linux/amd64,linux/arm64 -f SVR/Dockerfile -t ghcr.io/mackeyk24/babylon-game-server:$npm_package_version -t mackeyk24/babylon-game-server:$npm_package_version --push ."
+  },
+  "dependencies": {
+    "@babylonjs/havok": "1.3.14",
+    "@colyseus/ws-transport": "0.18.4",
+    "babylonjs": "9.35.0",
+    "babylonjs-gui": "9.35.0",
+    "babylonjs-loaders": "9.35.0",
+    "babylonjs-toolkit": "9.35.0",
+    "colyseus": "0.18.9",
+    "express": "5.3.0",
+    "ioredis": "5.11.1",
+    "jose": "6.2.12",
+    "prom-client": "15.1.3"
+  },
+  "devDependencies": {
+    "@colyseus/sdk": "0.18.5",
+    "@fails-components/webtransport": "1.6.2",
+    "@types/node": "22.15.3",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.1.2",
+    "qrcode-generator": "1.4.4",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "6.0.3",
+    "vite": "8.3.1"
+  },
+  "optionalDependencies": {
+    "@colyseus/h3-transport": "0.18.4"
+  }
+}

package/templates/init/Caddyfile

@@ -0,0 +1,6 @@
+# Caddy in front of the Babylon Game Server {{version}} (docker-compose.websocket.yml).
+# CADDY_SITE is your domain (Caddy gets and renews its certificate automatically) and defaults to :443.
+# CADDY_SITE=:8080 serves plain HTTP on 8080 for a local check.
+{$CADDY_SITE::443} {
+    reverse_proxy game-server:2567
+}

package/templates/init/DEPLOY.md

@@ -0,0 +1,233 @@
+# Deploying the Babylon Game Server {{version}}
+
+This folder was written by `babylon-game-server init`. It holds your server configuration and a ready recipe for each
+way of hosting it. Every recipe uses the published image `ghcr.io/mackeyk24/babylon-game-server:{{version}}` (also
+on Docker Hub as `mackeyk24/babylon-game-server:{{version}}`), either directly or through the `Dockerfile` here,
+which adds your `babylon-game-server.config.mjs`.
+
+TLS, UDP (HTTP/3 WebTransport) and player authentication are **off** in every file until you turn them on. Each
+recipe's header states where TLS ends (`edge`: the proxy or platform, `server`: the game server itself), whether its
+host can carry UDP, and how to enable auth.
+
+| File | What it is |
+|---|---|
+| `babylon-game-server.config.mjs` | Every setting at its default, with notes on enabling TLS, UDP and auth |
+| `.env.example` | Every setting as a `GAME_SERVER_*` environment variable |
+| `Dockerfile` | Your image: the published image plus your config |
+| `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/`, `fly.toml`, `railway.json`, `render.yaml`, `digitalocean-app.yaml`, `heroku.yml`, `app.json`, `colyseus-cloud/`, `kubernetes/` | Cloud and platform recipes (see [Platforms](#platforms)) |
+
+**Recommended host: Colyseus Cloud (`colyseus-cloud/`).** The server is built on Colyseus 0.18, and Colyseus Cloud is
+Colyseus's own hosting, at a fixed monthly price: `wss://` provided, one process per CPU sharing Redis, and rolling
+deploys that let running sessions finish. Its folder installs the published package instead of using the image; its
+`README.md` has every step. The other recipes run the same server anywhere else.
+
+## Production checklist
+
+1. **Point the game at the server.** Set the game's `serverUrl` (the Unity `NetworkSettings` component, or
+   `StartGameArgs`) to `wss://<your domain>`. Browsers block `ws://` from an `https://` page.
+2. **Decide on authentication.** With auth off, anyone who can reach the server can join (the server logs a warning
+   in production). To require players to sign in, set `GAME_SERVER_AUTH_ENABLED=true` and a mode
+   (`GAME_SERVER_AUTH_MODE`: `shared-secret`, `jwt` or `webhook`) with its fields, and have the game pass
+   `StartGameArgs.authToken`.
+   - **Discord sign-in (optional, works beside any mode):** register `https://<your domain>/game-server/discord/callback`
+     under OAuth2 → Redirects in your Discord application, set it as `GAME_SERVER_DISCORD_REDIRECT_URI`, and put the client
+     secret in `GAME_SERVER_DISCORD_CLIENT_SECRET` in your platform's secret store (with
+     `GAME_SERVER_DISCORD_SIGN_IN_ENABLED=true`, `GAME_SERVER_DISCORD_CLIENT_ID` and `GAME_SERVER_DISCORD_RETURN_ORIGINS`).
+3. **Restrict origins.** Set `GAME_SERVER_ALLOWED_ORIGINS` to your game's origins, e.g. `https://game.example.com`.
+4. **Protect the admin API.** The four original admin endpoints stay off until `GAME_SERVER_ADMIN_TOKEN` is set; use a
+   long random value from your platform's secret store. For scripts, prefer the console's API keys, which carry only
+   the permissions they need (`babylon-game-server admin create-api-key`).
+5. **Size instances for dedicated sessions.** Each Server-mode session runs the scene's simulation on the server
+   (`limits.maxDedicatedSessions` per process, default 4). Shared and Host sessions only relay, and are light.
+6. **When scaling out**, run Redis, set `GAME_SERVER_REDIS_URL` on every instance, and set
+   `GAME_SERVER_PUBLIC_ADDRESS` per instance to an address players can reach that instance on directly (seat
+   reservations send each player to the instance that holds the session).
+7. **Health checks:** liveness `GET /game-server/health`, readiness `GET /game-server/ready` (503 while draining or
+   when Redis is unreachable). On `SIGTERM` the server drains for `GAME_SERVER_DRAIN_SECONDS` (default 30): give the
+   platform at least that long before it kills the container.
+8. **Set up the admin console** (`/game-server/admin/`; README, "Admin console"):
+   - **HTTPS.** The console refuses plain HTTP except from a loopback address. Serve it on your TLS address (an edge
+     with `GAME_SERVER_TRUST_PROXY=true` that sends `x-forwarded-proto: https`, or TLS on the server).
+   - **Keep its data.** Accounts, bans, the audit log and the leaderboards live in Redis when `GAME_SERVER_REDIS_URL` is set, otherwise in
+     `GAME_SERVER_ADMIN_DATA_DIR` (`/data` in the image). Mount a volume at `/data` (the compose files and `fly.toml`
+     do), or use Redis with persistence (`docker-compose.full.yml`, `kubernetes/redis.yaml`). Platforms without
+     volumes (Railway, Render, DigitalOcean App Platform, Heroku, ECS Fargate) need Redis, or the console forgets its
+     accounts on every deploy.
+   - **Restrict who can reach it.** Set `GAME_SERVER_ADMIN_ALLOWED_NETWORKS` to your office or VPN ranges (CIDR), or
+     block `/game-server/admin/` at the edge. Requests from other addresses answer 404.
+   - **Create the first Owner.** The first start logs `admin setup link` (valid 30 minutes, used once): open it on your
+     HTTPS address, or run `babylon-game-server admin create-owner --username <name>` in the container. Every account
+     signs in with a password and an authenticator code or passkey.
+   - **Back up the data.** Copy the data folder (or snapshot the volume), or turn on Redis persistence and backups; it
+     holds the bans, the audit log and the leaderboards. The console's Leaderboards page warns when they are not
+     durable.
+
+## 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 …`).
+
+### WebSocket behind Caddy (`docker-compose.websocket.yml`)
+
+Caddy terminates HTTPS (it obtains and renews a certificate for your domain automatically) and proxies to the server,
+which publishes no ports of its own. Point your domain's DNS at the host and open TCP 443.
+
+```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
+```
+
+### TLS, HTTP/3 and Redis (`docker-compose.full.yml`)
+
+The server terminates TLS itself, so it can also offer HTTP/3 WebTransport over UDP on the same port 443.
+
+1. Get a certificate into `./certs` (`fullchain.pem`, `privkey.pem`), for example with certbot:
+   `certbot certonly --standalone -d game.example.com`, then copy the files from `/etc/letsencrypt/live/<domain>/`
+   (a certbot `--deploy-hook` can copy them on every renewal; the server reloads them without a restart, and HTTP/3
+   picks them up at the next restart).
+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.
+
+## Platforms
+
+Which transports each host can carry. WebSocket works everywhere; HTTP/3 WebTransport (UDP datagrams) needs a host
+that forwards inbound UDP to the server **and** TLS on the server itself. Players whose network or browser cannot use
+HTTP/3 fall back to the WebSocket automatically, so a WebSocket-only host is fully playable.
+
+| Host | WebSocket | UDP (HTTP/3) | TLS |
+|---|---|---|---|
+| Docker Compose + Caddy (`docker-compose.websocket.yml`) | yes | no (Caddy proxies TCP only) | edge (Caddy) |
+| Docker Compose full (`docker-compose.full.yml`) | yes | yes (443/udp published) | server |
+| AWS ECS Fargate + ALB (`aws/ecs-fargate-alb.yml`) | yes | no: [ALB listeners are HTTP/HTTPS only](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listeners.html) | edge (ALB) |
+| AWS ECS Fargate + NLB QUIC (`aws/ecs-fargate-nlb-quic.yml`) | yes | yes (`TCP_QUIC` listener) | server |
+| AWS single EC2 + Elastic IP (`aws/README.md`) | yes | yes (open UDP 443) | server |
+| AWS Elastic Beanstalk (`aws/README.md`) | yes | no: [ALB listeners are HTTP/HTTPS only](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listeners.html) | edge (ALB) |
+| Fly.io (`fly.toml`) | yes | no: [UDP must bind `fly-global-services`](https://docs.fly.io/networking/udp-and-tcp) | edge (Fly proxy) |
+| Railway (`railway.json`) | yes | no: [no inbound UDP](https://docs.railway.com/networking/tcp-proxy) | edge (Railway) |
+| Render (`render.yaml`) | yes | no: [HTTP and WebSocket only](https://render.com/docs/websocket) | edge (Render) |
+| DigitalOcean App Platform (`digitalocean-app.yaml`) | yes | no: [HTTP only](https://docs.digitalocean.com/products/app-platform/details/limits/) | edge (App Platform) |
+| Heroku (`heroku.yml`, `app.json`) | yes | no: [HTTP routing only](https://devcenter.heroku.com/articles/http-routing) | edge (Heroku router) |
+| Colyseus Cloud (`colyseus-cloud/`) | yes | no: its NGINX carries HTTP and WebSocket only | edge (Colyseus Cloud) |
+| Kubernetes (`kubernetes/`) | yes | only with server TLS and a UDP-capable LoadBalancer Service | edge (Ingress) or server |
+
+Every recipe below except Colyseus Cloud builds from the `Dockerfile` in this folder (the published image plus your
+config) or runs the published image directly, keeps server TLS, UDP and auth off unless the table says otherwise, and honours the
+platform's `PORT` when `GAME_SERVER_PORT` is not set.
+
+### AWS
+
+`aws/README.md` walks through three setups: ECS Fargate behind an Application Load Balancer (`aws/ecs-fargate-alb.yml`,
+WebSocket, TLS at the ALB, health `/game-server/ready`, idle timeout 3600 s), ECS Fargate behind a Network Load
+Balancer with a `TCP_QUIC` listener (`aws/ecs-fargate-nlb-quic.yml`, WebSocket + HTTP/3, TLS on the server from a
+Secrets Manager PEM secret), and one EC2 instance with an Elastic IP, plus Elastic Beanstalk notes.
+
+```sh
+aws cloudformation deploy --template-file aws/ecs-fargate-alb.yml --stack-name babylon-game-server \
+  --capabilities CAPABILITY_IAM \
+  --parameter-overrides VpcId=vpc-... SubnetIds=subnet-a,subnet-b CertificateArn=arn:aws:acm:...
+```
+
+### Fly.io (`fly.toml`)
+
+WebSocket only, TLS at Fly's edge on 443, readiness check on `/game-server/ready`. Fly hands UDP only to sockets bound
+to `fly-global-services`, while the server's HTTP/3 transport binds one address for TCP and UDP, so HTTP/3 is not
+offered ([Fly: UDP and TCP](https://docs.fly.io/networking/udp-and-tcp)).
+
+```sh
+fly launch --copy-config --no-deploy
+fly deploy
+# players use wss://<app>.fly.dev
+```
+
+### Railway (`railway.json`)
+
+TLS: edge. UDP: not supported on this host. Auth: set `GAME_SERVER_AUTH_*` in the service's variables to enable.
+(JSON has no comments, so this recipe's header lives here.) Railway builds the `Dockerfile`, checks
+`/game-server/ready`, and sets `PORT`. Its public networking is HTTP, plus a TCP proxy; there is no inbound UDP
+([Railway: TCP proxy](https://docs.railway.com/networking/tcp-proxy)).
+
+```sh
+railway init
+railway up
+railway domain        # players use wss://<generated domain>
+```
+
+### Render (`render.yaml`)
+
+A Docker web service with `healthCheckPath: /game-server/ready`; Render terminates TLS and supports WebSockets, but
+not inbound UDP ([Render: WebSockets](https://render.com/docs/websocket)). Commit this folder to a repository and
+create a Blueprint from it in the Render dashboard.
+
+### DigitalOcean App Platform (`digitalocean-app.yaml`)
+
+A service built from the `Dockerfile` with `http_port: 2567` and a health check on `/game-server/ready`. App Platform
+routes HTTP (including WebSockets) only ([App Platform limits](https://docs.digitalocean.com/products/app-platform/details/limits/)).
+Set `github.repo`, then:
+
+```sh
+doctl apps create --spec digitalocean-app.yaml
+```
+
+### Heroku (`heroku.yml`, `app.json`)
+
+The container stack builds the `Dockerfile`; `app.json` sets the stack, trusts the router's forwarding header, and
+shortens the drain to 25 s because Heroku stops a dyno 30 s after `SIGTERM`. The router carries HTTP and WebSockets
+only ([Heroku: HTTP routing](https://devcenter.heroku.com/articles/http-routing)).
+
+```sh
+heroku create --stack container
+git push heroku main
+```
+
+### Colyseus Cloud (`colyseus-cloud/`)
+
+The recommended host. WebSocket only, TLS at Colyseus Cloud's NGINX, one process per CPU sharing Redis. This folder is
+a deploy repository that installs the published package, so it uses neither the `Dockerfile` nor the image. Push it as a
+repository of its own, or as a subfolder of another repository with the panel's Root directory set to it. Its
+`README.md` has every step.
+
+```sh
+cd colyseus-cloud
+npm install                     # keep the package-lock.json this writes
+git init && git add . && git commit -m "Babylon Game Server on Colyseus Cloud"
+npx @colyseus/cloud deploy      # or connect the repository on the panel
+# the banner in the application logs shows wss://<your-application-address>
+```
+
+Set `NODE_ENV=production`, `GAME_SERVER_ALLOWED_ORIGINS` and `GAME_SERVER_ADMIN_TOKEN` on the panel. Leave
+`GAME_SERVER_TLS_ENABLED`, `GAME_SERVER_UDP_ENABLED` and `GAME_SERVER_PUBLIC_ADDRESS` unset: the server refuses to start
+with them. The drain time here is 600 s, and a process holding a `boot` dedicated session uses all of it on every
+deploy; `GAME_SERVER_DRAIN_SECONDS` changes it. After changing a boot scene, watch the logs for `the boot dedicated
+sessions could not start; trying again`: a bad scene does not fail a rolling deploy.
+
+### Kubernetes (`kubernetes/`)
+
+`deployment.yaml` runs the image with liveness `/game-server/health`, readiness `/game-server/ready`,
+`GAME_SERVER_REDIS_URL`, and a per-pod `GAME_SERVER_PUBLIC_ADDRESS` from the pod IP (downward API). `service.yaml` is
+a ClusterIP Service for an Ingress; `redis.yaml` is a single Redis Deployment and Service.
+
+```sh
+kubectl apply -f kubernetes/redis.yaml -f kubernetes/deployment.yaml -f kubernetes/service.yaml
+```
+
+Put a TLS Ingress in front of the Service for `wss://`. When scaling past one replica, each pod must be reachable on
+its own address, because seat reservations send each player to the pod that holds the session (see the comment in
+`service.yaml`). For HTTP/3, enable server TLS (mount the certificate from a Secret) and UDP, and expose the pods with a
+LoadBalancer Service that forwards both TCP and UDP on the same port.

package/templates/init/Dockerfile

@@ -0,0 +1,12 @@
+# Babylon Game Server {{version}}: your game's server image, built on the published base image.
+#   docker build -t my-game-server .
+#   docker run -p 2567:2567 my-game-server
+# The base image runs as user "node", exposes 2567/tcp and 2567/udp, and checks its own /game-server/health.
+# TLS: edge (a proxy or the platform terminates it) unless you enable it in the config.
+# UDP: off unless you enable it in the config (it also needs TLS and a host that forwards UDP).
+# Auth: set GAME_SERVER_AUTH_* to enable.
+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/

package/templates/init/app.json

@@ -0,0 +1,21 @@
+{
+  "name": "Babylon Game Server",
+  "description": "Babylon Game Server {{version}} for Babylon Toolkit multiplayer games. TLS: edge (the Heroku router). UDP: not supported on this host (WebSocket only). Auth: set GAME_SERVER_AUTH_* to enable.",
+  "stack": "container",
+  "env": {
+    "GAME_SERVER_TRUST_PROXY": {
+      "description": "The Heroku router sends the player's address in x-forwarded-for.",
+      "value": "true"
+    },
+    "GAME_SERVER_DRAIN_SECONDS": {
+      "description": "Seconds running sessions may continue after SIGTERM; Heroku stops a dyno 30 s after SIGTERM.",
+      "value": "25"
+    }
+  },
+  "formation": {
+    "web": {
+      "quantity": 1,
+      "size": "basic"
+    }
+  }
+}

package/templates/init/aws/README.md

@@ -0,0 +1,118 @@
+<!--
+TLS: edge (ecs-fargate-alb.yml, Elastic Beanstalk) or server (ecs-fargate-nlb-quic.yml, single EC2)
+UDP: supported with ecs-fargate-nlb-quic.yml and single EC2; not supported on this host with an ALB or Elastic Beanstalk
+Auth: set GAME_SERVER_AUTH_* to enable
+-->
+
+# Babylon Game Server {{version}} on AWS
+
+Three ways to run the server on AWS, from simplest to most capable. All of them use the published image
+`ghcr.io/mackeyk24/babylon-game-server:{{version}}`, or your own image built from `../Dockerfile` and pushed to ECR
+(pass it as the `Image` parameter). Nothing here is deployed for you: run the commands with your own AWS account.
+
+## ECS Fargate behind an Application Load Balancer (`ecs-fargate-alb.yml`)
+
+WebSocket only. The ALB terminates HTTPS with an ACM certificate for your domain, forwards to the tasks on port 2567,
+checks `/game-server/ready`, and keeps idle WebSockets for 3600 s.
+
+1. Request (or import) a certificate for your domain in ACM, in the stack's region.
+2. Deploy:
+
+   ```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
+   ```
+
+3. Point your domain at the `LoadBalancerDnsName` output (CNAME, or a Route 53 alias record), then set the game's
+   `serverUrl` to `wss://<your domain>`.
+
+## ECS Fargate behind a Network Load Balancer with QUIC (`ecs-fargate-nlb-quic.yml`)
+
+WebSocket **and** HTTP/3 WebTransport. A `TCP_QUIC` listener on 443 passes TCP and QUIC through to the tasks on 2567,
+and the server terminates TLS itself with a PEM certificate from Secrets Manager (`GAME_SERVER_TLS_CERT_PEM` /
+`GAME_SERVER_TLS_KEY_PEM`), with `GAME_SERVER_TLS_ENABLED=true` and `GAME_SERVER_UDP_ENABLED=true`.
+
+1. Store the certificate (for example from certbot) 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}')"
+   ```
+
+2. 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
+   ```
+
+3. Point your domain at the `LoadBalancerDnsName` output.
+
+QUIC listeners cannot have security groups, so the task security group admits 2567 TCP and UDP from anywhere. QUIC
+on Network Load Balancers is 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. A renewed certificate reaches
+`wss://` without a restart when it comes from files; from Secrets Manager it is read at task start, so roll the
+service (`aws ecs update-service --force-new-deployment`) after rotating the secret.
+
+## Alternative: one EC2 instance with an Elastic IP (HTTP/3 without a load balancer)
+
+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 (`certbot certonly --standalone -d game.example.com`) and copy `fullchain.pem` / `privkey.pem`
+   into `./certs`, readable by the container user.
+4. Run the image with TLS and UDP enabled, either with `../docker-compose.full.yml` or directly:
+
+   ```sh
+   docker run -d --restart unless-stopped -p 443:443/tcp -p 443:443/udp \
+     -v "$PWD/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 \
+     ghcr.io/mackeyk24/babylon-game-server:{{version}}
+   ```
+
+## Elastic Beanstalk notes
+
+- Use the **Docker** platform and deploy the folder with `../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.
+- WebSocket only: the ALB does not carry UDP, so HTTP/3 is not available on Beanstalk.
+
+## Scaling
+
+One task holds each session (a session never spans processes). To run more than one task, set `GAME_SERVER_REDIS_URL`
+on every task (for example ElastiCache) and give each task a `GAME_SERVER_PUBLIC_ADDRESS` that players can reach it on
+directly, because seat reservations send each player to the task that holds the session. A single load balancer
+address cannot do that on its own, so keep `DesiredCount=1` per stack until per-task addresses are in place.
+
+## Admin console data
+
+The admin console (`/game-server/admin/`) keeps its accounts, bans and audit log in Redis when `GAME_SERVER_REDIS_URL`
+is set, and otherwise in files under `GAME_SERVER_ADMIN_DATA_DIR` (`/data` in the templates). Fargate task storage is
+lost whenever a task stops or is replaced, so on ECS use Redis as the console's store: create an ElastiCache for Redis
+(or Valkey) cluster in the tasks' VPC, allow TCP 6379 from the task security group, and add `GAME_SERVER_REDIS_URL`
+(through Secrets Manager when it carries a password) to the container's `Environment` or `Secrets`. Turn on ElastiCache
+backups, because the audit log and the bans live there. Mounting an EFS volume at `/data` also works but is not part of
+these templates. The console needs HTTPS: the ALB template's HTTPS listener and the NLB template's server TLS both
+qualify. The first start logs `admin setup link` in CloudWatch: open its path
+(`/game-server/admin/#/setup?token=…`) on your HTTPS address within 30 minutes to create the first Owner, or run
+`babylon-game-server admin create-owner` against the same Redis.

package/templates/init/aws/ecs-fargate-alb.yml

@@ -0,0 +1,207 @@
+# TLS: edge (the Application Load Balancer terminates HTTPS with your ACM certificate)
+# UDP: not supported on this host (an ALB forwards HTTP and WebSocket only; see aws/ecs-fargate-nlb-quic.yml for HTTP/3)
+# Auth: set GAME_SERVER_AUTH_* to enable (add them to the container Environment below, secrets through Secrets Manager)
+#
+# Babylon Game Server {{version}} on ECS Fargate behind an Application Load Balancer: players connect with
+# wss://<your domain>, which you point (CNAME / alias) at the LoadBalancerDnsName output.
+# Long-form intrinsics only (Ref: / Fn::GetAtt:), so any YAML parser can check the template.
+#   aws cloudformation deploy --template-file aws/ecs-fargate-alb.yml --stack-name babylon-game-server \
+#     --capabilities CAPABILITY_IAM --parameter-overrides VpcId=vpc-... SubnetIds=subnet-a,subnet-b CertificateArn=arn:aws:acm:...
+# Keep DesiredCount at 1 unless sessions are routed to the task that holds them (see aws/README.md, Scaling).
+AWSTemplateFormatVersion: "2010-09-09"
+Description: Babylon Game Server {{version}} on ECS Fargate behind an Application Load Balancer (WebSocket, TLS at the ALB)
+
+Parameters:
+  VpcId:
+    Type: AWS::EC2::VPC::Id
+    Description: The VPC the load balancer and the tasks run in.
+  SubnetIds:
+    Type: List<AWS::EC2::Subnet::Id>
+    Description: Two or more public subnets in different availability zones.
+  CertificateArn:
+    Type: String
+    Description: ARN of the ACM certificate for your game server domain.
+  Image:
+    Type: String
+    Default: ghcr.io/mackeyk24/babylon-game-server:{{version}}
+    Description: The server image (or your own image built from the init Dockerfile).
+  DesiredCount:
+    Type: Number
+    Default: 1
+    Description: Number of server tasks.
+
+Resources:
+  Cluster:
+    Type: AWS::ECS::Cluster
+
+  LogGroup:
+    Type: AWS::Logs::LogGroup
+    Properties:
+      RetentionInDays: 14
+
+  TaskExecutionRole:
+    Type: AWS::IAM::Role
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              Service: ecs-tasks.amazonaws.com
+            Action: sts:AssumeRole
+      ManagedPolicyArns:
+        - arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
+
+  TaskDefinition:
+    Type: AWS::ECS::TaskDefinition
+    Properties:
+      Family: babylon-game-server
+      RequiresCompatibilities:
+        - FARGATE
+      NetworkMode: awsvpc
+      Cpu: "512"
+      Memory: "1024"
+      ExecutionRoleArn:
+        Fn::GetAtt: [TaskExecutionRole, Arn]
+      ContainerDefinitions:
+        - Name: game-server
+          Image:
+            Ref: Image
+          Essential: true
+          # Longer than the 30 s drain, so running sessions finish before the task is stopped.
+          StopTimeout: 45
+          PortMappings:
+            - ContainerPort: 2567
+              Protocol: tcp
+          Environment:
+            - Name: GAME_SERVER_LOG_FORMAT
+              Value: json
+            # Admin console data (accounts, bans, audit log). Fargate task storage is lost when the task stops: add
+            # GAME_SERVER_REDIS_URL (ElastiCache, see aws/README.md) so the console keeps its data in Redis.
+            - Name: GAME_SERVER_ADMIN_DATA_DIR
+              Value: /data
+            # The ALB sends the player's address in x-forwarded-for.
+            - Name: GAME_SERVER_TRUST_PROXY
+              Value: "true"
+          LogConfiguration:
+            LogDriver: awslogs
+            Options:
+              awslogs-group:
+                Ref: LogGroup
+              awslogs-region:
+                Ref: AWS::Region
+              awslogs-stream-prefix: game-server
+
+  LoadBalancerSecurityGroup:
+    Type: AWS::EC2::SecurityGroup
+    Properties:
+      GroupDescription: Babylon Game Server load balancer (HTTPS from anywhere)
+      VpcId:
+        Ref: VpcId
+      SecurityGroupIngress:
+        - IpProtocol: tcp
+          FromPort: 443
+          ToPort: 443
+          CidrIp: 0.0.0.0/0
+
+  ServiceSecurityGroup:
+    Type: AWS::EC2::SecurityGroup
+    Properties:
+      GroupDescription: Babylon Game Server tasks (port 2567 from the load balancer only)
+      VpcId:
+        Ref: VpcId
+      SecurityGroupIngress:
+        - IpProtocol: tcp
+          FromPort: 2567
+          ToPort: 2567
+          SourceSecurityGroupId:
+            Ref: LoadBalancerSecurityGroup
+
+  LoadBalancer:
+    Type: AWS::ElasticLoadBalancingV2::LoadBalancer
+    Properties:
+      Type: application
+      Scheme: internet-facing
+      Subnets:
+        Ref: SubnetIds
+      SecurityGroups:
+        - Ref: LoadBalancerSecurityGroup
+      LoadBalancerAttributes:
+        # WebSocket sessions stay open; the default 60 s idle timeout would cut quiet players.
+        - Key: idle_timeout.timeout_seconds
+          Value: "3600"
+
+  TargetGroup:
+    Type: AWS::ElasticLoadBalancingV2::TargetGroup
+    Properties:
+      VpcId:
+        Ref: VpcId
+      Protocol: HTTP
+      Port: 2567
+      TargetType: ip
+      HealthCheckProtocol: HTTP
+      HealthCheckPath: /game-server/ready
+      HealthCheckIntervalSeconds: 15
+      HealthyThresholdCount: 2
+      UnhealthyThresholdCount: 3
+      Matcher:
+        HttpCode: "200"
+      TargetGroupAttributes:
+        - Key: deregistration_delay.timeout_seconds
+          Value: "45"
+
+  HttpsListener:
+    Type: AWS::ElasticLoadBalancingV2::Listener
+    Properties:
+      LoadBalancerArn:
+        Ref: LoadBalancer
+      Port: 443
+      Protocol: HTTPS
+      SslPolicy: ELBSecurityPolicy-TLS13-1-2-2021-06
+      Certificates:
+        - CertificateArn:
+            Ref: CertificateArn
+      DefaultActions:
+        - Type: forward
+          TargetGroupArn:
+            Ref: TargetGroup
+
+  Service:
+    Type: AWS::ECS::Service
+    DependsOn: HttpsListener
+    Properties:
+      Cluster:
+        Ref: Cluster
+      LaunchType: FARGATE
+      DesiredCount:
+        Ref: DesiredCount
+      TaskDefinition:
+        Ref: TaskDefinition
+      HealthCheckGracePeriodSeconds: 30
+      NetworkConfiguration:
+        AwsvpcConfiguration:
+          # A public IP lets the task pull the image from ghcr.io without a NAT gateway.
+          AssignPublicIp: ENABLED
+          Subnets:
+            Ref: SubnetIds
+          SecurityGroups:
+            - Ref: ServiceSecurityGroup
+      LoadBalancers:
+        - ContainerName: game-server
+          ContainerPort: 2567
+          TargetGroupArn:
+            Ref: TargetGroup
+
+Outputs:
+  LoadBalancerDnsName:
+    Description: Point your game server domain (CNAME or Route 53 alias) here.
+    Value:
+      Fn::GetAtt: [LoadBalancer, DNSName]
+  HealthUrl:
+    Description: The readiness check through the load balancer (use your domain, which the certificate covers).
+    Value:
+      Fn::Join:
+        - ""
+        - - "https://"
+          - Fn::GetAtt: [LoadBalancer, DNSName]
+          - /game-server/ready