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

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 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
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
./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 caching in your browser's dev tools network tab so that ordinary page reloads will pick up changes.

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

Docker

You can find a fully-fledged environment setup using docker in the repo lichess.org/lila-docker.

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.