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.

★ Star on GitHub

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