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:
2026-11-03 14:36:14 +01:00
parent f37242ed29
commit 8ba87d8efe
2 changed files with 77 additions and 17 deletions
+7 -17
View File
@@ -12,27 +12,17 @@ Ready to run in production? Please [check our deployment guides](https://phoenix
## Local tablebases (optional)
Positions with five or fewer pieces are answered locally from Syzygy
tablebases when `TABLEBASE_PATH` points at a directory of `.rtbw`/`.rtbz`
files. When it is unset the trainer falls back to the Lichess API.
`TABLEBASE_PATH` lets each environment point at its own copy — it differs on a
dev machine and a VPS:
Positions with five or fewer pieces are answered locally from Syzygy tablebases
when `TABLEBASE_PATH` points at a directory of `.rtbw`/`.rtbz` files; otherwise
lookups fall back to Lichess.
```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
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
mix tablebase.fetch --path /path/to/syzygy/3-4-5 # once per host (~939 MB)
export TABLEBASE_PATH=/path/to/syzygy/3-4-5 # set per environment
```
On boot the app logs whether the local tablebases loaded and the largest piece
count they cover, so a wrong path shows up immediately.
See [docs/tablebases.md](docs/tablebases.md) for the full reference — dev vs
VPS paths, `mix tablebase.check`, and boot logging.
## Learn more