Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:
1

Java Development Kit (JDK)

Install JDK 21 or later. Lichess requires a full JDK, not just a JRE.
# Verify your Java installation
java -version
Make sure JAVA_HOME is set correctly and points to a JDK installation with the compiler module.
2

Node.js and pnpm

Install Node.js 24+ and pnpm 10 for building the frontend assets.
# Check Node version
node --version  # Should be >= 24

# pnpm is managed by package.json
# It will use pnpm 10.22.0 automatically
3

MongoDB

Install MongoDB for game data storage. Lichess expects MongoDB running on mongodb://127.0.0.1:27017.
# Start MongoDB (varies by OS)
# Linux/systemd:
sudo systemctl start mongodb

# macOS with Homebrew:
brew services start mongodb-community
4

Redis (Optional)

Redis is used for caching and real-time features. While optional for basic development, many features require it.
# Start Redis
# Linux/systemd:
sudo systemctl start redis

# macOS with Homebrew:
brew services start redis

​
Quick Setup

Get Lichess running locally in just a few commands:
1

Clone the Repository

git clone https://github.com/lichess-org/lila.git
cd lila
2

Configure Default Settings

The lila.sh script automatically creates default configuration files if they don’t exist:
  • .sbtopts - SBT memory and GC settings
  • conf/application.conf - Application configuration
These files are created from .default templates on first run.
The default .sbtopts file configures:
  • Initial heap: 2GB (-Xms2g)
  • Maximum heap: 8GB (-Xmx8g)
  • Stack size: 2MB (-Xss2m)
  • G1 garbage collector
You can adjust these in your .sbtopts file if needed.
3

Start the SBT Console

Run the lila.sh wrapper script to start SBT:
./lila.sh
This starts the Scala Build Tool (SBT) console. You’ll see the Lichess ASCII banner and the SBT prompt.
The first run will download all dependencies, which may take several minutes.
4

Compile and Run

Inside the SBT console, compile and run the application:
run
This compiles all Scala modules and starts the Play Framework server.
Initial compilation can take 10-15 minutes depending on your system. Subsequent compilations are much faster thanks to incremental compilation.
5

Build Frontend Assets

In a separate terminal, build the TypeScript/JavaScript frontend:
# Build once
ui/build

# Or watch for changes (recommended for development)
ui/build -w
The build script uses esbuild to bundle TypeScript modules and generates content-hashed assets in /public/compiled.

​
Access Your Local Instance

Once the server is running:
  1. Web Interface: Open http://localhost:9663 in your browser
  2. WebSocket Server: Runs on port 9664 (configured in conf/base.conf)
  3. API Endpoints: Available at http://localhost:9663/api/
The default development ports are:
  • HTTP: 9663
  • WebSocket: 9664
These can be changed in conf/base.conf or conf/application.conf.

​
Development Workflow

​
Making Changes

# In the SBT console:
# The server auto-reloads on code changes
# Just save your .scala files and refresh the browser

# To manually trigger recompilation:
~compile

# To run tests:
test

​
Running Tests

# In the SBT console:
test                    # Run all tests
testOnly *GameTest      # Run specific test

# Frontend tests:
ui/test                 # Run all UI tests
ui/test -w              # Watch mode
ui/test winning         # Run specific test file

​
Code Formatting

# Format Scala code:
./lila.sh scalafmtAll

# Or via pnpm:
pnpm format:scala

# Format TypeScript/JavaScript:
pnpm format

# Check formatting without changes:
pnpm check-format

​
Linting

# Lint TypeScript and Sass:
pnpm lint

# Auto-fix issues:
pnpm lint:fix

​
Configuration

​
Application Configuration

Key configuration files:
  • conf/application.conf: Your local overrides (gitignored)
  • conf/base.conf: Base configuration with defaults
  • conf/application.conf.default: Template for local config
Edit conf/application.conf:
http.port = 8080
Then restart the server.

​
Database Configuration

MongoDB URI is configured in conf/base.conf: 
mongodb {
  uri = "mongodb://127.0.0.1:27017?appName=lila"
}
Override in your conf/application.conf if you need different settings.

​
Common Issues

Increase heap size in .sbtopts:
-J-Xmx16g
Ensure MongoDB is running:
# Check if MongoDB is running
pgrep -l mongod

# Start MongoDB
sudo systemctl start mongodb  # Linux
brew services start mongodb-community  # macOS
Build the frontend assets:
ui/build
Make sure the build completes successfully and generates files in /public/compiled.
Change the port in conf/application.conf:
http.port = 9999
Or kill the process using the port:
lsof -ti:9663 | xargs kill -9

​
Next Steps

Architecture

Learn about Lichess system design and components

Contributing Guide

Read the full contributing guidelines

Development Wiki

Detailed setup instructions and tips

Discord Community

Ask questions and get help from developers

​
Additional Resources

  • Module Structure: Explore the 83 modules in /modules directory
  • Frontend Packages: TypeScript packages in /ui use pnpm workspace
  • Chess Logic: Pure chess implementation in scalachess submodule
  • API Documentation: https://lichess.org/api

Build docs developers (and LLMs) love

Get started for freeTalk to us