Files
tidewall/packaging/README.md
T
claudeandClaude Opus 5.5 8eb6e587fb N7: Dedicated server packaging, health endpoint and graceful shutdown
- packaging/server/tidewall-server: a wrapper that turns SIGTERM and SIGINT
  into a clean stop through the server's new --stop-file, since the engine
  can't catch signals. The server tells everyone it shut down, logs its
  statistics and exits 0; the wrapper kills it only after 15 s.
- --config=PATH reads options from a file (packaging/server/server.cfg);
  options after it on the command line win.
- --health-port answers GET /health with JSON (phase, players, tick, uptime)
  on loopback by default. HealthServer is non-blocking and bounded.
- packaging/docker: a debian:13 image that checks the engine against
  tools/engine.sha512, imports the game at build time, runs as an unprivileged
  user, and works with a read-only root and a small /tmp. compose.yaml is
  project and container tidewall-server, read-only, no capabilities.
- packaging/systemd: a hardened unit with a dynamic user.
- make server-package-check: compose up, healthy, non-root, read-only, a real
  headless client joins over UDP into the drop, then SIGTERM stops it cleanly.

This also covers H7 (graceful shutdown on SIGTERM).

Closes #38
Closes #70

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 22:07:24 -05:00

71 lines
3.2 KiB
Markdown

# Running a Tidewall dedicated server
A dedicated server is the game's engine running headless with `--server`. It needs no
display, GPU or sound, and logs one JSON object per line on stdout.
## What is here
| File | What it is |
|---|---|
| `server/tidewall-server` | The wrapper that starts the server. It turns SIGTERM and SIGINT into a clean stop, which the engine can't do itself. |
| `server/server.cfg` | An example configuration, one command-line option per line. Every option is described in `src/server/server_config.gd`. |
| `docker/Dockerfile` | A server image on `debian:13`. It runs as an unprivileged user, and the game is imported at build time, so the filesystem can be read-only. |
| `docker/compose.yaml` | An example Compose project, `tidewall-server`. |
| `systemd/tidewall-server.service` | A hardened systemd unit for running it without containers. |
## With Docker Compose
The image is built from the repository, which needs the pinned engine in `tools/godot/`
(see `tools/godot.sh`).
```bash
cd packaging/docker
docker compose up -d
```
Players connect to UDP port 24650 on the host (`TIDEWALL_PORT=24700 docker compose up -d`
picks another). `docker compose logs -f` follows the log, and `docker compose down`
stops the server cleanly: everyone connected is told it shut down.
To change settings, copy `server/server.cfg`, edit it and mount it over
`/etc/tidewall/server.cfg` (the commented `volumes` entry in `compose.yaml`).
LAN discovery answers on the game port plus one, but Docker's default bridge network
doesn't pass broadcasts. Give the service `network_mode: host` if people on your LAN
should find it in their server list; anyone can still join by address without it.
`make server-package-check` builds the image, starts it with Compose, joins it with a
headless client and stops it, checking each step.
## With systemd
The unit expects the layout the image uses:
- `/opt/tidewall/engine/godot`: the engine binary from `tools/godot/`,
- `/opt/tidewall/game/`: `project.godot`, `src/`, `data/` and the licences, imported once
with `godot --headless --path /opt/tidewall/game --import --quit`,
- `/usr/local/bin/tidewall-server`: the wrapper,
- `/etc/tidewall/server.cfg`: the configuration.
Then install `systemd/tidewall-server.service` and enable it. It runs under a dynamic
user with a private `/tmp`, a read-only system and no capabilities.
## Health and shutdown
With `health-port` set, `GET /health` on that TCP port answers 200 and a JSON body with
the match phase, player count and uptime. It listens on loopback unless `health-bind`
says otherwise; the container's health check uses it from inside.
Stopping: send SIGTERM to the wrapper (Docker, Compose and systemd all do). It creates
the server's stop file, the server disconnects everyone with a "shut down" reason, logs
its statistics and exits 0. If it hasn't gone within 15 seconds the wrapper kills it.
## Ports
| Port | Protocol | What |
|---|---|---|
| 24650 | UDP | Game traffic (`port`). |
| 24651 | UDP | LAN discovery and list-server registration (`port` + 1). |
| 24650 | TCP | Health endpoint (`health-port`), loopback only by default. |
| 24660 | UDP | A list server, if you run one (`--list-server`). |