Lichess Development Onboarding

Are you sure about this?

Before going further, be aware there is a full environment setup using docker in the repo lichess.org/lila-docker.

You can also try a web-based VSCode via GitPod (or connect your local VSCode to a GitPod). Just one click and you're ready to code!

Both are a great way to get started working on nearly every lichess service. You can then revisit this page as a reference if you want to get your hands dirty and find out what the little docker elves are doing inside their containers.

Alright then

The following instructions outline how to set up a bare metal development environment on Linux. For Windows, click here or for Mac, click here. A working knowledge of your platform (including basic command line tools) is assumed.

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 (https://discord.gg/lichess). The main developer of Lichess (thibault) can be found there as well as several people who have successfully installed the stack.

You may also find answers to other development-related questions in the GitHub Wiki.

Prerequisites

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

Hardware

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

Tools and dependency managers

• git
• java (JDK >= 21, type java --version to see if you need to update or use jenv if you need multiple jdk versions)
• cs (cs >= 2, installing coursier will provide sbt as well)
• node (node >= 22.6, install latest via NVM)
• pnpm (use corepack enable from the main repo directory after cloning) and (see the pnpm homepage if you'd like to install globally)

Running infrastructure

• mongodb (4.2 <= mongo <= 7.x, 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 on your machine, click here for quick and powerful setup.

Installation

Setup lila

git clone --recursive https://github.com/lichess-org/lila.git
cd lila
corepack enable # installs the right version of pnpm, the client package manager
mongosh lichess < bin/mongodb/indexes.js # creates database indexes
# or `mongosh mongodb://localhost:27017/lichess < lila/bin/mongodb/indexes.js` if you use docker
mongod # for this command and the redis-server one below, run them in separate terminals or as daemons
redis-server
sbt run -Dcsrf.origin=http://localhost:9663 # run this in a separate terminal in your cloned `lila-ws` repo (see instructions later on for this)
ui/build # builds client. -h for help, and -w to automatically compile new frontend changes and see them when refreshing the browser.
./lila.sh # 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. You may have to run the command a few times, if your system incrementally compiles the project.

When it's done, type run to start the HTTP server, and make sure your system has around 8GB of RAM available. Then open http://127.0.0.1:9663 in your browser (or http://localhost:9663 if that doesn't work).

Read more about the SBT console commands.

Setup websockets

Lichess uses the websockets protocol for real-time communication. Websocket connections are handled by the lila-ws server which lives outside of the main lila repo. Odds are you won't need to change it, but you will need to set it up.

To install:

git clone https://github.com/lichess-org/lila-ws.git
cd lila-ws
sbt run -Dcsrf.origin=http://localhost:9663

UI dev tip

Run pnpm add-hooks to configure the lila git workspace to format staged files with prettier/esling prior to every commit. All source files with the ts, js, or json extensions must pass lint.

Watch client typescript and scss code automatically using ui/build -w. Changes you make to source files will be detected, compiled, and available in your browser after a refresh.

Recommended: Seed database

You can use https://github.com/lichess-org/lila-db-seed to seed your local database with dummy data. use the spamdb.py script to populate your database (requires python 3.9+).

git clone https://github.com/lichess-org/lila-db-seed

cd lila-db-seed

python3 spamdb/spamdb.py --help

Optional: Setup Stockfish analysis

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

git clone --recursive https://github.com/lichess-org/fishnet.git
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 https://github.com/lichess-org/lila-fishnet.git
cd lila-fishnet
sbt app/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 https://github.com/lichess-org/fishnet.git
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

Development

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 eslint and/or prettier (coc-prettier is good for nvim), or type pnpm format in the project root.

Contributing

Most developers interact with their git repos on their local machine and those on GitHub with the git CLI command. If you don't want to use the command line, consider downloading and getting acquainted with GitHub Desktop for Windows, Mac, or Linux. It's a basic UI that can walk you through forking and contributing to a project like lila for the first time. You should still read the rest of this section to get a rough idea of how the CLI flow works.

Collaboration on the website front and back end is managed through the lila GitHub repo. Contributions are made using the GitHub Pull Request mechanism. First, ensure you have git installed and create a GitHub account. Next, fork the lila repo to your new account. Then follow the linked instructions to create and use a personal access token for authentication. After all that, here are some basic commands to get started.

  git clone https://github.com/YOUR-GITHUB-USERNAME/lila # fetch the sources
  git remote add upstream origin https://github.com/lichess-org/lila # link your repo to lichess-org/lila
  git checkout -b YOUR-BRANCH-NAME # branches are human readable & dash separated, otherwise your choice
  git add -A . # recursively stages all changes within the current directory
  git commit -m 'your commit message' # commit previously staged changes to your host repo
  git push origin YOUR-BRANCH-NAME # push the state of your local repo to your fork.
  # notice that git push's output contains a URL you can visit to create your Pull Request

A couple git configs that might ease your git workflow:

• git config branch.autoSetupMerge inherit
• git config push.autoSetupRemote true
• git config push.default current

Stream recordings

Troubleshooting

• [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 it 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:

  setParameter:
    maxBSONDepth: 999
  

• sbt prints Killed and exits

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

• Metals for VSCode not activating semantic features

  Try Metals: Run doctor through the command palette. If there is no obvious error, ensure that under Metals's extension settings, Java Home and Java Version are correctly set (JDK >= 21 for lila). Other language server extensions can interfere unexpectedly with Metals, so it may also be worth disabling all extensions.