# 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. ```sh # 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. ```sh 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). ```sh 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 (largest=5)` - `local Syzygy tablebases disabled (TABLEBASE_PATH unset)` - `local Syzygy tablebases at contain no files` - `local Syzygy tablebases failed: ` ## 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`.