Skip to content

Setup

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.

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.

Stream recordings

https://www.youtube.com/watch?v=AejdHlL902w

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

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

If you need websockets (which you probably do):

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 -w. 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.

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/

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

Collaboration on the website front and back end is managed through the lila GitHub repo. You may contribute using the GitHub Pull Request mechanism. Assuming you have git installed, a GitHub account with authentication in place, a fork of the lila repo - the following commands will get you started.

  git clone --single-branch --filter=blob:none https://github.com/YOUR-USERNAME/lila # get the sources
  # git clone --single-branch --filter=blob:none git@github.com:YOUR-USERNAME/lila.git # operate over SSH
  git remote add upstream https://github.com/lichess-org/lila # add a ref for the parent repo
  git checkout -b YOUR-BRANCH # branches are human readable & dash separated, otherwise your choice
  # make your edits to sources
  git add -A # stages all changes
  git commit -m 'your commit message' # commit staged changes to git on your host
  # you might want to rebase against master and resolve conflict(s) before pushing
  git push origin YOUR-BRANCH # 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:

If you don't want to use the command line, I don't blame you! Consider downloading and getting acquainted with GitHub Desktop for Windows, Mac, or Linux. It's a basic UI with menus and things to click and will walk you through forking a project for the first time. Most will find it less intimidating than the command line procedures. But if you want even more command line, there is a dedicated GitHub CLI for you to try out!

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): https://github.com/keaaw/howto/blob/main/lichess-dev.md

Alternatives

Docker

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.

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 exceptions 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.