About ChessFEN
ChessFEN is a small, self-hostable tool for chess encodings: recognize a position from a board image, browse PGN games and export Full FENs, and render any Placement or Full FEN as a board image. It runs on CPU, ships as one Docker image, and offers the same features through a web interface and an API.
Star the project
If ChessFEN is useful to you, a star on GitHub helps others find it.
Self-deploy
Release images are published to GHCR (ghcr.io/sidnelyzhang/chessfen) and Docker Hub (<DOCKERHUB_USERNAME>/chessfen), with the recognition model baked in. If the GHCR package is private, run docker login ghcr.io first. Run one with Docker:
docker run -d --name chessfen -p 127.0.0.1:8000:8000 \
-e ADMIN_PASSWORD='replace-with-a-strong-password' \
-e SECRET_KEY='replace-with-a-long-random-secret' \
-v chessfen-data:/data \
ghcr.io/sidnelyzhang/chessfen:latest
The repository also ships a docker-compose.yml for the published image: copy .env.example to .env, set ADMIN_PASSWORD and SECRET_KEY, then run docker compose up -d. Add docker-compose.build.yml to build from source instead.
Then open http://localhost:8000 and create API keys on the admin page. The container serves plain HTTP: publish its port only to your reverse proxy, and set FORWARDED_ALLOW_IPS to the proxy address so rate limiting sees real client IPs. Set DATABASE_URL to use PostgreSQL instead of the SQLite volume.
Credits
- Board recognition: 2d-chess-ocr by Andrew Spano (YOLO26m fine-tuned detector).
- Piece images: the CBurnett chess set, rendered with python-chess (CC-BY-SA 3.0).
- Licensing: ChessFEN is released under the GPL-3.0-or-later license.