N7 Dedicated server packaging #38

Closed
opened 2026-11-09 05:28:22 +00:00 by claude · 1 comment
Owner

Depends on: F6, N1

Provide a server configuration file, a systemd unit, a Dockerfile and a Compose example, with graceful shutdown and a health endpoint. Build locally only, without pushing images or deploying.

Acceptance

  • docker compose up in the example starts a joinable server, tested with a headless client.
  • Runs as a non-root user with a read-only filesystem where practical.
  • Compose project and container names use the prefix tidewall-.
**Depends on:** F6, N1 Provide a server configuration file, a systemd unit, a Dockerfile and a Compose example, with graceful shutdown and a health endpoint. Build locally only, without pushing images or deploying. **Acceptance** - `docker compose up` in the example starts a joinable server, tested with a headless client. - Runs as a non-root user with a read-only filesystem where practical. - Compose project and container names use the prefix `tidewall-`.
claude added this to the v0.5 Multiplayer milestone 2026-11-09 05:28:22 +00:00
claude added the priority/hightype/feature labels 2026-11-09 05:28:22 +00:00
claude added this to the Tidewall v1.0 project 2026-11-09 15:00:08 +00:00
eric closed this issue 2026-11-13 03:07:34 +00:00
Author
Owner

Done in 8eb6e58.

What changed

  • packaging/server/tidewall-server: a wrapper that turns SIGTERM and SIGINT into a clean stop. The engine can't catch signals, so the wrapper creates the server's new --stop-file. The server then disconnects everyone with the "shut down" reason, logs stats and stop, and exits 0. If it hasn't gone after 15 s the wrapper kills it.
  • --config=PATH reads one option per line (packaging/server/server.cfg is the example). Command-line options given after it win.
  • --health-port=N makes GET /health answer 200 with JSON: phase, players, max players, tick and uptime. It listens on loopback unless --health-bind says otherwise. HealthServer never blocks, holds at most 8 connections, and drops slow or oversized requests.
  • packaging/docker/Dockerfile is built on debian:13. It checks the engine against tools/engine.sha512, imports the game at build time, and runs as uid 10650. It has a HEALTHCHECK that uses /health from inside the container.
  • packaging/docker/compose.yaml: project and container are both named tidewall-server. The container is read_only, has a 64 MB tmpfs /tmp, drops all capabilities and sets no-new-privileges. TIDEWALL_PORT picks the host port.
  • packaging/systemd/tidewall-server.service: a dynamic user, ProtectSystem=strict, no capabilities, KillMode=mixed so only the wrapper gets SIGTERM.
  • packaging/README.md explains each file, the ports, and why LAN discovery needs network_mode: host under Docker.

Testing

  • make server-package-check runs the whole path. It builds with Compose, waits for healthy, and checks the server isn't uid 0. Writes to /opt/tidewall/game and /etc fail. /health answers. A real headless client joins over UDP through Docker's port mapping and gets from the lobby into the drop with 0 bad packets. docker compose stop gives exit 0, and the log shows stopping (stop file) and a clean stop line. It passed twice, the second time on the final code.
  • New unit tests cover /health JSON, 404s and dropped requests, plus config-file order and errors and the new options.
  • make check passes: 491 tests and smoke.
  • systemd-analyze verify passes on the unit with the binary path replaced. The unit hasn't been installed or run under systemd on any host.

The image was built locally only (tidewall-server:dev). Nothing was pushed or deployed.

— tidewall-build

Done in 8eb6e58. **What changed** - `packaging/server/tidewall-server`: a wrapper that turns SIGTERM and SIGINT into a clean stop. The engine can't catch signals, so the wrapper creates the server's new `--stop-file`. The server then disconnects everyone with the "shut down" reason, logs `stats` and `stop`, and exits 0. If it hasn't gone after 15 s the wrapper kills it. - `--config=PATH` reads one option per line (`packaging/server/server.cfg` is the example). Command-line options given after it win. - `--health-port=N` makes `GET /health` answer 200 with JSON: phase, players, max players, tick and uptime. It listens on loopback unless `--health-bind` says otherwise. `HealthServer` never blocks, holds at most 8 connections, and drops slow or oversized requests. - `packaging/docker/Dockerfile` is built on `debian:13`. It checks the engine against `tools/engine.sha512`, imports the game at build time, and runs as uid 10650. It has a `HEALTHCHECK` that uses `/health` from inside the container. - `packaging/docker/compose.yaml`: project and container are both named `tidewall-server`. The container is `read_only`, has a 64 MB tmpfs `/tmp`, drops all capabilities and sets `no-new-privileges`. `TIDEWALL_PORT` picks the host port. - `packaging/systemd/tidewall-server.service`: a dynamic user, `ProtectSystem=strict`, no capabilities, `KillMode=mixed` so only the wrapper gets SIGTERM. - `packaging/README.md` explains each file, the ports, and why LAN discovery needs `network_mode: host` under Docker. **Testing** - `make server-package-check` runs the whole path. It builds with Compose, waits for `healthy`, and checks the server isn't uid 0. Writes to `/opt/tidewall/game` and `/etc` fail. `/health` answers. A real headless client joins over UDP through Docker's port mapping and gets from the lobby into the drop with 0 bad packets. `docker compose stop` gives exit 0, and the log shows `stopping` (stop file) and a clean `stop` line. It passed twice, the second time on the final code. - New unit tests cover `/health` JSON, 404s and dropped requests, plus config-file order and errors and the new options. - `make check` passes: 491 tests and smoke. - `systemd-analyze verify` passes on the unit with the binary path replaced. The unit hasn't been installed or run under systemd on any host. The image was built locally only (`tidewall-server:dev`). Nothing was pushed or deployed. — tidewall-build
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: claude/tidewall#38