From 9e0f6f17ef346699e56a9f16eb80d420ca9ecc4c Mon Sep 17 00:00:00 2001 From: mwiegand Date: Sat, 9 May 2026 10:09:40 +0200 Subject: [PATCH] docs(deploy): performance-tuning escape-hatch section in README Documents CPU governor, per-instance CPUAffinity, NIC tuning, and SCHED_FIFO opt-in patterns. None of these are auto-applied; they're ops-side knobs for measured problems the perf baseline doesn't solve. --- deploy/README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/deploy/README.md b/deploy/README.md index 8250187..f890a23 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -71,3 +71,64 @@ The web app currently supports two overlay surfaces: - `script` overlays — populated by an arbitrary user-authored bash script that runs inside `bubblewrap` + `systemd-run --scope` as the unprivileged `l4d2-sandbox` UID, with the overlay directory bind-mounted RW at `/overlay`. Resource caps: 1h walltime, 4 GB RAM, 512 tasks, 200% CPU, 20 GB post-build disk cap. Both the caches and the overlay directories are owned by the `left4me` runtime user; if the web service ever runs as a different uid, ensure it shares a group with the host process and that both trees are group-readable. + +## Performance Tuning + +The deployment ships a host-side perf baseline (slices, unit directives, sysctls). See `docs/superpowers/specs/2026-05-09-l4d2-server-host-perf-baseline-design.md` for design rationale. + +The following knobs are documented escape hatches — they are **not** auto-applied. Apply only if you have measured a need and understand the failure modes. + +### CPU governor + +The performance governor squeezes a few percent off jitter under bursty load. `schedutil` is acceptable for sustained UDP workloads. + +```sh +sudo cpupower frequency-set -g performance +``` + +Persist via your distro's CPU-frequency tooling (e.g. `/etc/default/cpufrequtils`). + +### Per-instance CPU affinity + +`srcds` is single-threaded per instance. On a multi-core host, pinning each instance to its own core can cut jitter under contention. Drop in `/etc/systemd/system/left4me-server@.service.d/affinity.conf`: + +```ini +[Service] +CPUAffinity=2 +``` + +A reasonable strategy on an N-core host: leave core 0 for the kernel + IRQs + system services, then pin one instance per remaining core. + +### NIC tuning + +Hardware-specific. On a host with a single primary interface (replace `eth0`): + +```sh +sudo ethtool -G eth0 rx 4096 tx 4096 +sudo ethtool -K eth0 gro on lro off +``` + +If you run a high instance count, also pin the NIC's interrupts off the cores that game servers occupy (see `/proc/interrupts` and `/proc/irq//smp_affinity`). + +### Real-time scheduling (advanced, opt-in) + +Source-engine servers do not need real-time scheduling, and a misbehaving `srcds` at any RT priority can starve kernel threads — even with the default `kernel.sched_rt_runtime_us=950000` throttling 5% of CPU back. Use only if you have a measured jitter problem that the baseline does not solve. + +`/etc/systemd/system/left4me-server@.service.d/realtime.conf`: + +```ini +[Service] +CPUSchedulingPolicy=fifo +CPUSchedulingPriority=10 +LimitRTPRIO=10 +``` + +### Applying changes to running servers + +Unit-file changes do not apply to already-running services. After any change: + +```sh +sudo systemctl daemon-reload +# Restart each game server via the web UI's stop + start, or: +sudo systemctl restart 'left4me-server@*.service' +```