mirror of
https://github.com/TheRealOwenRees/chess-endgame-trainer.git
synced 2026-11-18 11:42:07 +00:00
Document TABLEBASE_PATH and local tablebase setup (#31)
Add docs/tablebases.md covering the local/Lichess routing, the TABLEBASE_PATH environment variable (dev vs VPS), the fetch/check mix tasks, boot logging, and the release build requirement. Link it from the README.
This commit is contained in:
@@ -12,27 +12,17 @@ Ready to run in production? Please [check our deployment guides](https://phoenix
|
|||||||
|
|
||||||
## Local tablebases (optional)
|
## Local tablebases (optional)
|
||||||
|
|
||||||
Positions with five or fewer pieces are answered locally from Syzygy
|
Positions with five or fewer pieces are answered locally from Syzygy tablebases
|
||||||
tablebases when `TABLEBASE_PATH` points at a directory of `.rtbw`/`.rtbz`
|
when `TABLEBASE_PATH` points at a directory of `.rtbw`/`.rtbz` files; otherwise
|
||||||
files. When it is unset the trainer falls back to the Lichess API.
|
lookups fall back to Lichess.
|
||||||
|
|
||||||
`TABLEBASE_PATH` lets each environment point at its own copy — it differs on a
|
|
||||||
dev machine and a VPS:
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
# Fetch the complete 3/4/5-piece WDL+DTZ set (~939 MB) once per host.
|
mix tablebase.fetch --path /path/to/syzygy/3-4-5 # once per host (~939 MB)
|
||||||
mix tablebase.fetch --path /path/to/syzygy/3-4-5
|
export TABLEBASE_PATH=/path/to/syzygy/3-4-5 # set per environment
|
||||||
mix tablebase.check --path /path/to/syzygy/3-4-5
|
|
||||||
|
|
||||||
# Dev
|
|
||||||
TABLEBASE_PATH=/path/to/syzygy/3-4-5 mix phx.server
|
|
||||||
|
|
||||||
# Production
|
|
||||||
TABLEBASE_PATH=/data/syzygy/3-4-5 bin/chesstrainer start
|
|
||||||
```
|
```
|
||||||
|
|
||||||
On boot the app logs whether the local tablebases loaded and the largest piece
|
See [docs/tablebases.md](docs/tablebases.md) for the full reference — dev vs
|
||||||
count they cover, so a wrong path shows up immediately.
|
VPS paths, `mix tablebase.check`, and boot logging.
|
||||||
|
|
||||||
## Learn more
|
## Learn more
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,70 @@
|
|||||||
|
# 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)
|
||||||
|
TABLEBASE_PATH=/data/syzygy/3-4-5 bin/chesstrainer start
|
||||||
|
```
|
||||||
|
|
||||||
|
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`.
|
||||||
Reference in New Issue
Block a user