- 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>
3.2 KiB
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).
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 fromtools/godot/,/opt/tidewall/game/:project.godot,src/,data/and the licences, imported once withgodot --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). |