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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tb8pW2KAN4oFkh1aK1BfD8
This commit is contained in:
Claude 2026-10-09 20:10:09 +00:00
parent faf0cfa603
commit 45dea022ae

View file

@ -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