Files
owenrees 73ba25afe3 Add cookieless Matomo analytics and opt-out (#131) (#133)
* Align Postgres version on 18.6

* Document production tablebase path and permissions

* Add cookieless Matomo analytics with opt-out (#131)
2026-11-10 10:12:48 +01:00

3.2 KiB
Raw Permalink Blame History

Tablebases

The trainer answers endgame positions from two sources, chosen by piece count (kings included):

Pieces Source
5 or fewer Local Syzygy files, probed through the Fathom NIF
6–7 Lichess tablebase API, cached
8 or more Not covered — rejected before any lookup

If a local probe fails (files missing, partial set, probe error), the lookup falls back to Lichess, so play only blocks when both sources are unavailable.

TABLEBASE_PATH

The local backend reads its directory from the TABLEBASE_PATH environment variable at boot (config/runtime.exs). It is environment-specific: a dev machine and a VPS will point at different copies.

# Development
export TABLEBASE_PATH=/home/you/Downloads/tablebase
mix phx.server

# Production (release), behind systemd
TABLEBASE_PATH=/opt/chesstrainer/tablebases bin/chesstrainer start

On the production VPS the directory is /opt/chesstrainer/tablebases, owned by the chesstrainer user. Set TABLEBASE_PATH in /etc/chesstrainer/env rather than an interactive shell, then restart chesstrainer.service — the value is read at boot.

sudo chown -R chesstrainer:chesstrainer /opt/chesstrainer/tablebases
sudo chmod -R u=rwX,g=rX,o= /opt/chesstrainer/tablebases
sudo systemctl restart chesstrainer
curl -s http://127.0.0.1:4100/health

Healthy local tablebases report tablebase: "local" and status: "ok". A missing, empty, or unreadable directory reports tablebase: "fallback" or "not_configured" and status: "degraded", still with HTTP 200 because the Lichess fallback is available.

The value must reach the process. A bare TABLEBASE_PATH=... line in bash only sets a shell variable and is not exported to mix or the release — use export, or prefix the command. For a release, systemd unit or container, set it in that service's environment, not an interactive shell.

When TABLEBASE_PATH is unset the local backend is disabled and every lookup falls back to Lichess (subject to its rate limits).

Installing the files

Fathom expects the .rtbw (WDL) and .rtbz (DTZ) files flat in the directory; both sets are required (WDL for the result, DTZ for optimal-move ranking and the 50-move-rule categories).

mix tablebase.fetch --path /path/to/syzygy/3-4-5   # ~939 MB, resumable
mix tablebase.fetch --path /path/to/syzygy/3-4-5 --dry-run
mix tablebase.check --path /path/to/syzygy/3-4-5   # verifies it loads

mix tablebase.check exits non-zero when the path is unset, contains no files, or Fathom cannot initialise it.

Boot logging

On startup the app logs one of:

  • local Syzygy tablebases ready at <path> (largest=5)
  • local Syzygy tablebases disabled (TABLEBASE_PATH unset)
  • local Syzygy tablebases at <path> contain no files
  • local Syzygy tablebases failed: <reason>

Deployment note

The Fathom NIF is compiled to priv/native/fathom_nif.so and ships inside the release. Whichever machine builds the release therefore needs the Rust toolchain (and crates.io access); the runtime host only needs the release artefact plus the tablebase files.

See docs/adr/0001-tablebase-via-lichess-api.md (predates local probing) and docs/adr/0004-tablebase-cache-shape-and-scaling.md.