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>
This commit is contained in:
@@ -0,0 +1,70 @@
|
||||
# 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`). |
|
||||
@@ -0,0 +1,45 @@
|
||||
# A Tidewall dedicated server image. Build it from the repository's root, which must
|
||||
# hold the pinned engine in tools/godot/ (see tools/godot.sh):
|
||||
#
|
||||
# docker build -f packaging/docker/Dockerfile -t tidewall-server:dev .
|
||||
#
|
||||
# or let packaging/docker/compose.yaml do it. The engine is checked against
|
||||
# tools/engine.sha512 before it goes in. The game is imported while building, so at
|
||||
# run time the image needs no writable filesystem apart from a small /tmp.
|
||||
FROM debian:13
|
||||
|
||||
ARG ENGINE=tools/godot/Godot_v4.7.2-stable_linux.x86_64
|
||||
|
||||
RUN groupadd --system --gid 10650 tidewall \
|
||||
&& useradd --system --uid 10650 --gid tidewall --home-dir /nonexistent --no-create-home --shell /usr/sbin/nologin tidewall
|
||||
|
||||
COPY tools/engine.sha512 /tmp/engine.sha512
|
||||
COPY ${ENGINE} /opt/tidewall/engine/godot
|
||||
RUN expected="$(awk '$2 ~ /_linux\.x86_64$/ { print $1 }' /tmp/engine.sha512)" \
|
||||
&& actual="$(sha512sum /opt/tidewall/engine/godot | cut -d' ' -f1)" \
|
||||
&& [ -n "$expected" ] && [ "$expected" = "$actual" ] \
|
||||
&& chmod 0755 /opt/tidewall/engine/godot \
|
||||
&& rm /tmp/engine.sha512
|
||||
|
||||
COPY project.godot LICENSE LICENSE-ASSETS /opt/tidewall/game/
|
||||
COPY src /opt/tidewall/game/src
|
||||
COPY data /opt/tidewall/game/data
|
||||
COPY packaging/server/tidewall-server /usr/local/bin/tidewall-server
|
||||
COPY packaging/server/server.cfg /etc/tidewall/server.cfg
|
||||
|
||||
# Import once here, so the server never has to write into the game's directory.
|
||||
RUN XDG_DATA_HOME=/tmp/import XDG_CONFIG_HOME=/tmp/import XDG_CACHE_HOME=/tmp/import \
|
||||
/opt/tidewall/engine/godot --headless --path /opt/tidewall/game --import --quit >/dev/null 2>&1 ; \
|
||||
test -d /opt/tidewall/game/.godot \
|
||||
&& rm -rf /tmp/import \
|
||||
&& chmod 0755 /usr/local/bin/tidewall-server
|
||||
|
||||
USER tidewall
|
||||
ENV TIDEWALL_STATE=/tmp/tidewall-server
|
||||
# Game traffic, LAN discovery, and the health check (TCP, on loopback by default).
|
||||
EXPOSE 24650/udp 24651/udp
|
||||
STOPSIGNAL SIGTERM
|
||||
HEALTHCHECK --interval=10s --timeout=3s --start-period=20s --retries=3 \
|
||||
CMD ["bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/24650 && printf 'GET /health HTTP/1.0\\r\\n\\r\\n' >&3 && head -n 1 <&3 | grep -q ' 200 '"]
|
||||
ENTRYPOINT ["/usr/local/bin/tidewall-server"]
|
||||
CMD ["--config=/etc/tidewall/server.cfg"]
|
||||
@@ -0,0 +1,32 @@
|
||||
# An example Tidewall dedicated server. From this directory:
|
||||
#
|
||||
# docker compose up -d builds the image from the repository and starts it
|
||||
# docker compose logs -f the server's JSON log lines
|
||||
# docker compose down stops it cleanly: players are told it shut down
|
||||
#
|
||||
# TIDEWALL_PORT changes the UDP port on the host (default 24650). To change anything
|
||||
# else, mount your own server.cfg over /etc/tidewall/server.cfg (see the commented
|
||||
# volume below) or add options to `command`.
|
||||
name: tidewall-server
|
||||
|
||||
services:
|
||||
server:
|
||||
build:
|
||||
context: ../..
|
||||
dockerfile: packaging/docker/Dockerfile
|
||||
image: tidewall-server:dev
|
||||
container_name: tidewall-server
|
||||
restart: unless-stopped
|
||||
command: ["--config=/etc/tidewall/server.cfg", "--port=${TIDEWALL_PORT:-24650}"]
|
||||
ports:
|
||||
- "${TIDEWALL_PORT:-24650}:${TIDEWALL_PORT:-24650}/udp"
|
||||
read_only: true
|
||||
tmpfs:
|
||||
- /tmp:size=64m,mode=1777
|
||||
cap_drop:
|
||||
- ALL
|
||||
security_opt:
|
||||
- no-new-privileges:true
|
||||
stop_grace_period: 20s
|
||||
# volumes:
|
||||
# - ./server.cfg:/etc/tidewall/server.cfg:ro
|
||||
@@ -0,0 +1,34 @@
|
||||
# Tidewall dedicated server configuration. Read with --config=PATH; each line is one
|
||||
# of the server's command-line options without the leading dashes (see
|
||||
# src/server/server_config.gd for all of them). Options given on the command line
|
||||
# after --config win over these.
|
||||
|
||||
# Take players over the network. Without this the server plays a bot-only match.
|
||||
listen
|
||||
|
||||
# UDP port players connect to. LAN discovery answers on this port plus one.
|
||||
port = 24650
|
||||
|
||||
# Fill each match's empty places with bots (any number above 0 turns it on).
|
||||
bots = 1
|
||||
# bot-difficulty = mixed
|
||||
|
||||
# The name shown in server browsers.
|
||||
name = Tidewall server
|
||||
|
||||
# Register with a list server so people outside the LAN can find this one.
|
||||
# list = lists.example.org:24660
|
||||
|
||||
# Don't answer LAN discovery broadcasts.
|
||||
# no-lan
|
||||
|
||||
# Answer GET /health on this TCP port, on loopback unless health-bind says otherwise.
|
||||
health-port = 24650
|
||||
# health-bind = 127.0.0.1
|
||||
|
||||
# A progress line in the log every this many ticks (30 a second). 0 for none.
|
||||
log-every = 9000
|
||||
|
||||
# A fixed seed makes every match on the island sequence repeatable. Leave it out for a
|
||||
# fresh one each start.
|
||||
# seed = 12345
|
||||
Executable
+47
@@ -0,0 +1,47 @@
|
||||
#!/usr/bin/env bash
|
||||
# Runs a Tidewall dedicated server and turns SIGTERM or SIGINT into a clean stop: the
|
||||
# server tells everyone connected it is shutting down, logs its statistics and exits 0.
|
||||
# The engine can't catch signals itself, so this wrapper creates the server's
|
||||
# --stop-file when one arrives, and kills the server only if it hasn't gone after
|
||||
# TIDEWALL_STOP_SECONDS (default 15).
|
||||
#
|
||||
# tidewall-server [server options...] e.g. --config=/etc/tidewall/server.cfg
|
||||
#
|
||||
# Where things are, overridable from the environment:
|
||||
# TIDEWALL_HOME the install: engine/godot and game/ (default /opt/tidewall)
|
||||
# TIDEWALL_ENGINE the engine binary (default $TIDEWALL_HOME/engine/godot)
|
||||
# TIDEWALL_GAME the game's project directory (default $TIDEWALL_HOME/game)
|
||||
# TIDEWALL_STATE a writable directory for the engine's own files and the stop file
|
||||
# (default $RUNTIME_DIRECTORY under systemd, else /tmp/tidewall-server)
|
||||
set -u
|
||||
|
||||
home="${TIDEWALL_HOME:-/opt/tidewall}"
|
||||
engine="${TIDEWALL_ENGINE:-$home/engine/godot}"
|
||||
game="${TIDEWALL_GAME:-$home/game}"
|
||||
state="${TIDEWALL_STATE:-${RUNTIME_DIRECTORY:-/tmp/tidewall-server}}"
|
||||
grace="${TIDEWALL_STOP_SECONDS:-15}"
|
||||
stop_file="$state/stop"
|
||||
|
||||
mkdir -p "$state/data" "$state/config" "$state/cache"
|
||||
rm -f "$stop_file"
|
||||
# The engine writes its user data and caches here, so the install can stay read-only.
|
||||
export XDG_DATA_HOME="$state/data" XDG_CONFIG_HOME="$state/config" XDG_CACHE_HOME="$state/cache"
|
||||
|
||||
"$engine" --headless --path "$game" -- --server --stop-file="$stop_file" "$@" &
|
||||
child=$!
|
||||
|
||||
request_stop() {
|
||||
touch "$stop_file"
|
||||
# If it hasn't stopped in time, stop it the hard way.
|
||||
( sleep "$grace"; kill -KILL "$child" 2>/dev/null ) &
|
||||
}
|
||||
trap request_stop TERM INT
|
||||
|
||||
wait "$child"
|
||||
code=$?
|
||||
# A trapped signal interrupts wait; keep waiting until the server has really gone.
|
||||
while kill -0 "$child" 2>/dev/null; do
|
||||
wait "$child"
|
||||
code=$?
|
||||
done
|
||||
exit "$code"
|
||||
@@ -0,0 +1,45 @@
|
||||
# A Tidewall dedicated server as a systemd service. It expects the layout the Docker
|
||||
# image uses: the engine at /opt/tidewall/engine/godot, the imported game in
|
||||
# /opt/tidewall/game, the wrapper at /usr/local/bin/tidewall-server and the
|
||||
# configuration in /etc/tidewall/server.cfg. Then:
|
||||
#
|
||||
# sudo cp tidewall-server.service /etc/systemd/system/
|
||||
# sudo systemctl daemon-reload && sudo systemctl enable --now tidewall-server
|
||||
# journalctl -u tidewall-server -f
|
||||
#
|
||||
# systemctl stop sends SIGTERM to the wrapper, which asks the server to stop cleanly.
|
||||
[Unit]
|
||||
Description=Tidewall dedicated server
|
||||
Documentation=https://gitea.eom.dev/claude/tidewall
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/local/bin/tidewall-server --config=/etc/tidewall/server.cfg
|
||||
# Only the wrapper gets SIGTERM; it passes the request on and waits.
|
||||
KillMode=mixed
|
||||
KillSignal=SIGTERM
|
||||
TimeoutStopSec=20
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
DynamicUser=yes
|
||||
RuntimeDirectory=tidewall-server
|
||||
Environment=TIDEWALL_STATE=%t/tidewall-server
|
||||
ProtectSystem=strict
|
||||
ProtectHome=yes
|
||||
PrivateTmp=yes
|
||||
PrivateDevices=yes
|
||||
NoNewPrivileges=yes
|
||||
ProtectKernelTunables=yes
|
||||
ProtectKernelModules=yes
|
||||
ProtectControlGroups=yes
|
||||
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
|
||||
RestrictNamespaces=yes
|
||||
LockPersonality=yes
|
||||
CapabilityBoundingSet=
|
||||
SystemCallArchitectures=native
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
Reference in New Issue
Block a user