From 45dea022ae37d68fbc264c4f9bbec3d96827cc90 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 9 Oct 2026 20:10:09 +0000 Subject: [PATCH] README: add setup guide for a Debian 13 LXC behind nginx Proxy Manager Install steps, systemd service, the Proxy Host settings (Websockets Support on, Let's Encrypt, HTTP/2), optional IPv6, verification and update flow, with a pointer to docs/DEPLOY.md for the details. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Tb8pW2KAN4oFkh1aK1BfD8 --- README.md | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 76 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0fdee96..32e1df0 100644 --- a/README.md +++ b/README.md @@ -25,11 +25,84 @@ npm start # http://localhost:8080 (prints your LAN URLs too) Open the printed URL on any device on your network. Pick a map and press **Play solo**, or **Co-op online** to create a room and send the invite link (or the 4-letter code) to a friend. -Solo only: you can also just open `public/index.html` in a browser. +Solo only: you can also just open `public/index.html` in a browser (the built-in synth music plays; your own tracks +need the server, because browsers block loading the track list from a `file://` page). Environment variables: `PORT` (8080), `HOST` (`::`, dual-stack IPv4 + IPv6), `TRUST_PROXY`, `ALLOWED_ORIGINS`, -`MAX_CONN_PER_IP`, `GRACE_MS`. Deployment in a Debian LXC behind nginx Proxy Manager (WebSockets, TLS, IPv6, systemd) -is in [docs/DEPLOY.md](docs/DEPLOY.md). +`MAX_CONN_PER_IP`, `GRACE_MS`. Full reference and troubleshooting: [docs/DEPLOY.md](docs/DEPLOY.md). + +## Setup guide: Debian 13 LXC behind nginx Proxy Manager + +The game is one small Node process (static files + a WebSocket at `/ws`), so the proxy only has to forward HTTP and +WebSockets. Nothing is stored on disk; a restart ends running games. + +### 1. Install it in the LXC (as root) + +```bash +apt update && apt install -y nodejs npm git # Debian 13 ships Node 20, which is plenty (18+ works) +git clone ssh://forgejo@int.git.vanvikinternet.no/jvanvik/towerdef.git /opt/netwall +cd /opt/netwall && npm install --omit=dev # only "ws" + +useradd --system --home-dir /opt/netwall --shell /usr/sbin/nologin netwall +install -m 0644 deploy/netwall.service /etc/systemd/system/netwall.service +systemctl daemon-reload && systemctl enable --now netwall + +curl http://127.0.0.1:8080/healthz # -> ok +curl -g 'http://[::1]:8080/healthz' # -> ok (the server listens on IPv4 and IPv6 at once) +journalctl -u netwall -f # live log +``` + +The service listens on `[::]:8080` (dual stack) and runs as the unprivileged `netwall` user. Change `PORT`, `HOST`, +`TRUST_PROXY` or `ALLOWED_ORIGINS` in the unit's `Environment=` lines (or `systemctl edit netwall`) and +`systemctl restart netwall`. If the unit fails with a sandboxing error inside an unprivileged Proxmox container, +comment out the line it names (see the notes in `deploy/netwall.service`). + +### 2. Add a Proxy Host in nginx Proxy Manager + +**Hosts > Proxy Hosts > Add Proxy Host** + +| Tab / field | Value | +|---|---| +| Details: Domain Names | `game.example.com` (your name for it) | +| Details: Scheme | `http` | +| Details: Forward Hostname / IP | the LXC's IP address | +| Details: Forward Port | `8080` | +| Details: Cache Assets | **off** | +| Details: **Websockets Support** | **on** (without it the page loads but co-op cannot connect) | +| SSL: Certificate | Request a new SSL Certificate (Let's Encrypt), **Force SSL** on, **HTTP/2** on | +| Advanced (optional) | `proxy_read_timeout 3600s;` and `proxy_send_timeout 3600s;` for very long idle games | + +NPM passes the original `Host` header through, which is what the server's WebSocket origin check expects, so no +extra configuration is needed. If the server log ever shows `refused websocket ... does not match Host` (HTTP 403 on +the upgrade), set `ALLOWED_ORIGINS=https://game.example.com` in the unit and restart. + +### 3. IPv6 (optional) + +The server side is already dual stack. Publish an `AAAA` record for the game name **after** your proxy really answers +on IPv6 (`curl -6 -I https://game.example.com/`); a published but broken `AAAA` breaks IPv6 visitors and certificate +issuance. The proxy-to-LXC hop can stay IPv4. + +### 4. Check it, play it + +```bash +curl -i https://game.example.com/healthz # 200 ok +``` + +Open `https://game.example.com/` on two phones, press **Co-op online**, create a room on one and tap the invite link +(or type the 4-letter code) on the other. On a phone, "Add to Home Screen" gives a full-screen app. + +Lock the LXC down so that only the proxy can reach port 8080 (firewall example in `docs/DEPLOY.md`). + +### 5. Update + +```bash +cd /opt/netwall && git pull && npm install --omit=dev && systemctl restart netwall +``` + +Running games end with the restart (players see the room is gone and can create a new one). + +Under a path prefix such as `https://example.com/netwall/`, the proxy must strip the prefix; see section 7 of +[docs/DEPLOY.md](docs/DEPLOY.md). A dedicated sub-domain is simpler. ## How to play