Smoke e2e, docs consistency pass, status summary
Built: e2e/run.js + lib.js (playwright-core, in-process server, temp DB): desktop flow, phone touch portrait/landscape, layout matrix on 5 viewports x pop/map/trade/world (overflow + console errors), WebSocket push incoming-banner without reload. 61/61 checks, ~54 s, identical over 4 runs; the push and overflow checks were shown to fail when the behaviour is removed. Docs: fixed stale numbers/claims in DESIGN, DECISIONS, BALANCE, API (undocumented routes, rate limits, notification types), DEPLOY, NEXT (status-at-a-glance on top). Deploy path exercised in a scratch dir: migrations, healthz, signup/build, admin CLI, SIGKILL catch-up, backup restore. Tested: npm test 207/207, npm run e2e 61/61, bot run 50x14d INVARIANTS OK. NOT tested: Chromium only; no systemd/nginx Proxy Manager/Node 22.13 run; e2e does not cover units, alliances, messages, trade or end-game flows beyond empty-state rendering; no nb, PWA or polling-fallback e2e; docs/workflows/ still empty. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
This commit is contained in:
parent
931f59e11e
commit
cc0524de5e
8 changed files with 533 additions and 38 deletions
|
|
@ -1,7 +1,7 @@
|
|||
# Deploying UPSTREAM
|
||||
|
||||
UPSTREAM is one Node process: it serves the static client from `public/`, the REST API under `/api/v1/` and (stage 6)
|
||||
a WebSocket at `/ws`. Unlike NETWALL it **keeps state**: one SQLite file, owned by that process. A restart loses
|
||||
UPSTREAM is one Node process: it serves the static client from `public/`, the REST API under `/api/v1/` and a
|
||||
WebSocket push channel at `/ws` (docs/PROTOCOL.md). Unlike NETWALL it **keeps state**: one SQLite file, owned by that process. A restart loses
|
||||
nothing: overdue events are caught up in order before the server accepts traffic.
|
||||
|
||||
```
|
||||
|
|
@ -17,6 +17,10 @@ layer. The differences are the Node version (`node:sqlite` needs 22.13+), a stat
|
|||
|
||||
* **Run:** `systemd-analyze verify` on the three unit files (syntax and directives only), the CLI `tools/admin.js`
|
||||
and its tests on a dev machine (Node 24.21), a backup, verify and prune cycle, `sh -n` on `deploy/upstream-admin`.
|
||||
Re-checked on 2026-10-11 with the code as it is now (Node 24.21, scratch directory, no systemd): first boot with `DB_PATH`/`PORT`/`HOST`
|
||||
(migrations 001-004 applied, `created world 1`), `/healthz`, `/` headers, signup + build over the API, `admin.js` status / worlds / users /
|
||||
operators / inspect-town / events / replay-events / backup / verify-backup / ban / unban / grant / end-world (refusal without `--yes`),
|
||||
SIGTERM and restart (state, queue and password kept, no migrations re-applied; tokens revoked by `ban` stay revoked), SIGKILL then restart after a build fell due (`caught up 1 overdue event(s)`, the build level was applied), and a restore by copying a snapshot to a fresh `DB_PATH` and starting on it (section 7: it logged `caught up 1 overdue event(s)`).
|
||||
* **Taken from NETWALL's docs, not re-run for UPSTREAM:** everything about nginx Proxy Manager (labels, header
|
||||
behaviour, "Client addresses"). NETWALL's guide records what was observed against NPM v2.16.0.
|
||||
* **Never run:** a Proxmox LXC, a started unit under systemd, the timer firing on its own, a Node install from the
|
||||
|
|
@ -163,8 +167,8 @@ line, no `export`) or in a `systemctl edit upstream` override, then `systemctl r
|
|||
| `DB_PATH` | `/var/lib/upstream/game.db` | SQLite file. The code default is `./data/game.db`; the unit overrides it. Its directory is created if missing, it must be writable by the service user. `-wal` and `-shm` files appear next to it: always copy via a snapshot (section 7), never with `cp` while running. |
|
||||
| `TRUST_PROXY` | `auto` | `auto`: believe `X-Forwarded-For` / `X-Forwarded-Host` only from loopback / private-range peers. `1`: always (then firewall the port). `0`: never. Used for the per-IP rate limits and the log. |
|
||||
| `TRUSTED_PROXIES` | empty | Extra IPs / CIDRs `auto` believes: needed when the proxy reaches the LXC from a global IPv6, Tailscale / CGNAT `100.64.0.0/10` or another routable address. |
|
||||
| `ALLOWED_ORIGINS` | empty | Extra origins for the WebSocket origin check (stage 6), comma separated, with the port when it is not 80/443. The REST API uses bearer tokens (no cookies) and does not check origins. |
|
||||
| `MAX_CONN_PER_IP` | `40` | Open connections per client address (WebSocket cap, stage 6). `0` disables. |
|
||||
| `ALLOWED_ORIGINS` | empty | Extra origins for the WebSocket origin check, comma separated, with the port when it is not 80/443. The REST API uses bearer tokens (no cookies) and does not check origins. |
|
||||
| `MAX_CONN_PER_IP` | `40` | Open WebSockets per client address (HTTP connections are not capped). `0` disables. |
|
||||
| `WORLD_SPEED` | unset (1) | World speed multiplier, **first boot only**, when the database has no world yet. |
|
||||
| `WORLD_RADIUS` | unset (50) | Map radius in tiles (coordinates `-R..R`, so 50 = 101 x 101), **first boot only**. |
|
||||
| `WORLD_NAME` | unset (`World 1`) | Name of the first world, **first boot only**. |
|
||||
|
|
@ -193,7 +197,7 @@ In NPM: **Hosts > Proxy Hosts > Add Proxy Host**.
|
|||
| Details: Forward Port | `8080` |
|
||||
| Details: Cache Assets | **off** (static files are `no-cache` and revalidated by ETag; the game must see new versions) |
|
||||
| Details: Block Common Exploits | optional |
|
||||
| Details: **Websockets Support** | **on.** The REST game works without it, but stage 6 adds `/ws` and it fails with HTTP 426 when this is off. Switch it on now so you do not forget. |
|
||||
| Details: **Websockets Support** | **on.** The REST game works without it, but `/ws` (live push) fails with HTTP 426 when this is off. |
|
||||
| Custom Locations | none needed |
|
||||
| SSL | Request a new Let's Encrypt certificate, **Force SSL**, **HTTP/2** (HSTS optional) |
|
||||
| Advanced (gear) | nothing required; optional gzip below |
|
||||
|
|
@ -214,9 +218,9 @@ Notes carried over from NETWALL's setup (observed there against NPM v2.16.0, not
|
|||
shares one rate-limit budget and the log shows the proxy's address. Fix: `TRUSTED_PROXIES=<its address or CIDR>`.
|
||||
* Clients on your own LAN can pick their address through NPM's `real_ip` handling, so the per-IP limits protect against
|
||||
public abuse, not against LAN users.
|
||||
* **Heads-up for stage 6:** NPM's default `proxy_read_timeout` is 90 s. NETWALL never idles because it streams 20
|
||||
snapshots a second; UPSTREAM's socket will be quiet for long stretches. The WebSocket server must send a ping
|
||||
well under 90 s (NETWALL's pings every 25 s), or the proxy drops idle players.
|
||||
* **Idle timeout:** nginx's `proxy_read_timeout` is 60 s by default (NETWALL's notes say 90 s for NPM; not re-checked). NETWALL never
|
||||
idles because it streams 20 snapshots a second; UPSTREAM's socket is quiet for long stretches. `server/push.js` sends a protocol ping
|
||||
every 30 s (`wsPingMs`), below either value, which is reasoning, not a measurement behind a real NPM.
|
||||
|
||||
Firewall and dual stack: identical to NETWALL (`docs/DEPLOY.md` there, section 6): only the proxy needs to reach port
|
||||
8080. `curl -i http://127.0.0.1:8080/healthz` and `curl -gi 'http://[::1]:8080/healthz'` check both families.
|
||||
|
|
@ -233,7 +237,7 @@ upstream-admin help
|
|||
upstream-admin status # file, size, migrations, overdue events
|
||||
upstream-admin worlds
|
||||
upstream-admin create-world --name "Summer" --speed 2 --radius 60 --seed 1234 --end-in 90d
|
||||
upstream-admin end-world 1 --yes
|
||||
upstream-admin end-world 1 --yes # flag flip only, see below
|
||||
upstream-admin users [--banned] # no hashes or tokens are ever printed
|
||||
upstream-admin operators [--world 1]
|
||||
upstream-admin ban mallory # sets banned, revokes all tokens: old tokens give 401, login 403
|
||||
|
|
@ -259,6 +263,9 @@ Safety rules the CLI follows:
|
|||
* Destructive or test-only commands refuse without a flag: `end-world` and `grant` need `--yes`; `reset-world`
|
||||
needs `--yes-destroy` (without it, it prints what it would delete and exits 2). `ban`, `unban`, `revoke-tokens` are
|
||||
reversible and need none.
|
||||
* `end-world` just sets the world's status to `ended` (and `end_at` to now): signup and join stop and every game command answers
|
||||
`world_ended`, but it writes no ranking snapshot (`GET /worlds/:id/results` stays `available: false`), cancels no pending event and
|
||||
closes no trade offer. The natural end (a backbone winner, then the `worldEnd` event two world days later) does all of that.
|
||||
* `reset-world` deletes the world's game rows (everything with a `world_id`, plus tables pointing at them: towns,
|
||||
buildings, events, operators, alliances, messages, ... discovered from the schema, so tables added by later stages
|
||||
are covered) and **keeps accounts and tokens**; players must join the world again. It resets `start_at`, clears
|
||||
|
|
@ -394,4 +401,4 @@ A healthy server has **no overdue events** in `status`: the timer processes even
|
|||
| `upstream-backup.service` failed | `journalctl -u upstream-backup`. Typical: disk full, or the integrity check of the new snapshot failed (then nothing was kept and nothing pruned; check the disk and the `game.db` itself). |
|
||||
| Backups not appearing | `systemctl list-timers upstream-backup.timer`; the timer must be **enabled** (`systemctl enable --now upstream-backup.timer`), not just installed. |
|
||||
| World reset by mistake | Restore the snapshot taken before (section 7), or the one `reset-world --backup` wrote. |
|
||||
| (stage 6) WebSocket upgrade answered 426 / 403 / 429 | 426: **Websockets Support** off in NPM. 403: origin check, see `ALLOWED_ORIGINS` and the notes in section 5. 429: more than `MAX_CONN_PER_IP` sockets from one address. |
|
||||
| WebSocket upgrade answered 426 / 403 / 429 | 426: **Websockets Support** off in NPM. 403: origin check, see `ALLOWED_ORIGINS` and the notes in section 5. 429: more than `MAX_CONN_PER_IP` sockets from one address. |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue