Files
chess-endgame-trainer/docs/tablebases.md
T
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

88 lines
3.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <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`.