Lichess Development Onboarding - lichess-org/lila GitHub Wiki

The following instructions outline how to set up your development environment for starting development on Lichess. The instructions are aimed to be agnostic of the platform the stack is installed on, so a working knowledge of the specifics of your GNU/Linux distribution or other such Unix based operating system is assumed.

You can set up the environment on a Windows machine or on macOS.

You can also try lichess development with a web-based vscode via GitPod. Just one click and you're ready to code!

Getting Help

If you get stuck during the installation process the most suitable place to seek help is the #lichess-dev-onboarding channel on Discord ( The main developer of Lichess (thibault) can be found there as well as several people who have successfully installed the stack.

Stream recordings


Before beginning, please make sure you have the following tools installed, using your favourite package manager to install them where applicable.


  • At least 4 GB of RAM
  • A CPU with 64-bit architecture.

Tools and dependency managers

Running infrastructure

  • mongodb (mongo >= 4.2, instructions, WSL2)
    • For WSL2, you might want to manually create the default /data/db directory and give ownership permissions to your user (sudo chown -R `id -un` /data/db). If sudo service mongod start does not work, you may want to open a terminal and run mongod as super-user.
  • redis

Alternatively, if you have setup docker-compose on your machine, write a docker-compose.yml file:

version: "3.3"
    image: redis:6-alpine
      - 6379:6379
    image: mongo:5.0
    restart: always
    container_name: lila_mongo
      - 27017:27017
      # use `docker exec -it lila_mongo bash` to get a shell inside mongo
      # container. Directory containing this docker-compose.yml will be mounted
      # as /host inside container so you can import db dumps, etc.
      - .:/host
      - lila_mongo_data:/data/db

  lila_mongo_data: {}

and spin up a redis and mongodb instance with:

docker-compose up


Setup lila

git clone --recursive
cd lila
mongosh lichess < bin/mongodb/indexes.js # creates database indexes
# or `mongosh mongodb://localhost:27017/lichess < lila/bin/mongodb/indexes.js` if you use docker
ui/build # builds client. -h for help and -w for incremental watch mode.
./lila # starts the SBT console

Once the console has booted, you will see a lila> prompt. Type compile and sit back. The full compilation takes 5 minutes on GitHub CI servers.

When it's done, type run to start the HTTP server. Then open in your browser.

Read more about the SBT console commands.

Setup websockets

If you need websockets (which you probably do):

git clone
cd lila-ws
sbt run -Dcsrf.origin=http://localhost:9663

UI dev tip

When watching client code using ui/build -w, changes you make to source files will be instantly compiled and available in your browser after a hard refresh. You may also disable asset caching in your browser inspector so that ordinary page reloads will pick up changes as well.

Recommended: Seed database

You can use to seed your local database with dummy data.

git clone

For users, games, puzzles, teams, forums, blogs, game histories, timelines, activity, and more - use the script to populate your database (requires python 3.9+).

pip3 install pymongo
python3 lila-db-seed/spamdb/ --help

Or, you may install game & puzzle data only:

cd lila-db-seed
mongorestore dump

Optional: Setup Stockfish analysis

Start a fishnet client for analysis (requires a recent Rust toolchain to build from source, alternatives):

git clone --recursive
cd fishnet
cargo run -- --endpoint http://localhost:9663/fishnet/

Optional: Setup "Play with the computer"

lila-fishnet enables playing vs Stockfish (not needed for analysis):

git clone
cd lila-fishnet
sbt run -Dhttp.port=9665

You will also need a client. Start a fishnet client for play against the machine (requires a recent Rust toolchain to build from source, alternatives):

git clone --recursive
cd fishnet
cargo run -- --endpoint http://localhost:9665/fishnet/

Optional: Setup Search

Follow these instructions to enable game, forum, team, and study search on Lila


Learn more about using pnpm and ui/build to work on client code

Bloop based setup for hacking lila scala code

Set up bloop for quick builds and IDE features.

Code formatting

These repositories use scalafmt for Scala and prettier for everything else.

Please install scalafmt for your editor, or run scalafmtAll in the sbt console before submitting code.

Likewise, pick a plugin for prettier (coc-prettier is good for nvim), or type pnpm format in the project root.

Other miscellaneous tips

Here are some hints for working on various parts of the system.

Spamdb creates a lichess admin user and a number of mod accounts listed at the top of lila-db-seed/spamdb/data/uids.txt. If you want to make an admin user manually, connect to the lichess db with mongo lichess and run

db.user4.update({ _id: "your_id" }, {$set: {roles: ["ROLE_SUPER_ADMIN"]}})

With your_id being the username in lowercase.

Installation and running notes from a new lichess-dev contributor, with detailed installation command line log and tips for running (e.g., in order to access lichess-dev from an outside system):



Here is a Docker setup that allows running lila and all services required for it in a Docker container. Running in Docker simplifies setup and guarantees that your development environment will perfectly match that of anyone else who uses that setup, eliminating the "it works on my machine" phenomena. However, it is always more performant to run any project directly on its host machine.

IntelliJ IDE (instructions need updating)

Here is a guide on how to set up lila with the IntelliJ IDE.


  • [PrimaryUnavailableException$: MongoError['No primary node is available!']]

    Make sure mongod is running, check /var/log/mongo/mongod.log for errors. It might not start if you have too little free space (might need 3GB), or if there is a previous lock file that hasn't been cleaned up (maybe try removing /var/lib/mongodb/mongod.lock)

  • Can't create games

    [ERROR] p.c.s.n.PlayDefaultUpstreamHandler Cannot invoke the action
    java.lang.ArrayIndexOutOfBoundsException: 101

    Check mongo --version, and that is satisfies the requirement at the top of this page.

  • java.util.concurrent.TimeoutException: Future timed out after [5 seconds]

    Check that MongoDB is running. Restart lila, if it was started before MongoDB. On OS X, the connection timeout might be needed to be increased initially (5 seconds could be too short for a cold start). See #6718.

  • Mongo error when Lila running

    [error] reactivemongo.api.Cursor - fails to send request
    reactivemongo.core.errors.DatabaseException$$anon$1: DatabaseException['error processing query: ns=lichess.challenge limit=50Tree: $and

    or similar excptions due to missing indexes: Run mongo lichess bin/mongodb/indexes.js again.

  • Mongo error when importing games

    DatabaseException['cannot insert document because it exceeds 180 levels of nesting' (code = 15)]?

    In /etc/mongodb.conf:

      maxBSONDepth: 999
  • sbt prints Killed and exits

    Most likely there was not enough free RAM to compile lila.