* Align Postgres version on 18.6 * Document production tablebase path and permissions * Add cookieless Matomo analytics with opt-out (#131)
3.2 KiB
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 fileslocal 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.