Lichess Development Onboarding

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 (or connect your local VSCode to a 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 (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.

Stream recordings

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 4 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 >= 14.3, install via NVM preferred) or (install node only)
pnpm (pnpm 8.7+, type npm i -g pnpm after installing node) or (see the pnpm homepage)

Running infrastructure

mongodb (5.1 >= 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"
services:
  redis:
    image: redis:6-alpine
    ports:
      - 6379:6379
  mongo:
    image: mongo:5.0
    restart: always
    container_name: lila_mongo
    ports:
      - 27017:27017
    volumes:
      # 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

volumes:
  lila_mongo_data: {}

and spin up a redis and mongodb instance with:

docker-compose up

Installation

Setup lila

git clone --recursive https://github.com/lichess-org/lila.git
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 http://127.0.0.1:9663 in your browser.

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 prior to every commit. You may also install a prettier plugin in your code editor to format on save. All source files with the ts, js, or json extensions must be prettified.

Watch client typescript and scss code automatically using ui/build -r. Changes you make to source files will be detected, 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 https://github.com/lichess-org/lila-db-seed to seed your local database with dummy data.

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

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

pip3 install pymongo
python3 lila-db-seed/spamdb/spamdb.py --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 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 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 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 upstream origin https://github.com/your-account/lila
  git checkout -b YOUR-BRANCH-NAME # branches are human readable & dash separated, otherwise your choice
  git add -A # stages all changes
  git commit -m 'your commit message' # commit staged changes to git on your host
  git push origin YOUR-BRANCH-NAME # push the state of your local git 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

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 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:

setParameter:
  maxBSONDepth: 999

sbt prints Killed and exits

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

Enjoy lichess!

Things to contribute

Uh oh!

Uh oh!

Lichess Development Onboarding

Getting Help

Stream recordings

Prerequisites

Hardware

Tools and dependency managers

Running infrastructure

Installation

Setup lila

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.

UI dev tip

Recommended: Seed database

Optional: Setup Stockfish analysis

Optional: Setup "Play with the computer"

Optional: Setup Search

Development

Bloop based setup for hacking lila scala code

Code formatting

Contributing

Troubleshooting

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally