make stability (tools/stability.sh, StabilityReport) runs one dedicated server for 50 bot matches back to back, unthrottled, sampling its resident memory, and fails on a crash, hang, engine or script error, a match with no winner, or memory that grows after the first five matches. The first run had no crash, hang or error, but showed two leaks: - ServerLoop kept every tick's duration in an array (8 bytes a tick, about 21 MB a day at 30 Hz) and copied and sorted all of it for every progress line. TickTimes keeps exact statistics in fixed memory: a one-microsecond histogram up to 65 ms, plus the rare slower ticks. - Resident memory grew about 28 MB a match (905 MB after 42 matches): glibc gives each thread its own malloc arena, and every next island is built on a worker thread. The server launchers (packaging/server, packaging/dist, so also the .deb, Docker image and systemd unit) and tools/godot.sh for --server now set MALLOC_ARENA_MAX=1 unless already set. Tick times were unchanged (p50 501 vs 507 us, p99 1635 vs 1625). After: 50 matches (seed 4242) in 756 s, all with a winner, exit 0, no errors; static memory +1.6 KiB and resident +145 KiB a match, flat at 204 MB from match 26 on. No match crashed, so there is no crash seed to turn into a regression test. Tests: TickTimes against a sorted list, its fixed memory, the launchers' setting, and StabilityReport. make check, dist-check and server-package-check pass. Closes #57 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
79 lines
3.5 KiB
Markdown
79 lines
3.5 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.
|
|
|
|
## Memory
|
|
|
|
The launchers set `MALLOC_ARENA_MAX=1` unless it is already set. The server builds each
|
|
next island on a worker thread, and with glibc's default of an arena per thread its
|
|
resident memory grew about 28 MB a match for as long as it ran. With one arena it stays
|
|
flat, about 200 MB with 24 bots, at no measured cost to tick time. `make stability`
|
|
checks this over 50 matches.
|
|
|
|
## 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`). |
|