Overview
Lichess (lila) is built with Scala 3, Play Framework 2.8, and TypeScript. This guide will help you set up a complete development environment.
Prerequisites
Before you begin, ensure you have the following installed:
Required
- Java Development Kit (JDK) 21+: Required for running Scala and sbt
- Node.js v24.11.1+: Required for UI development
- pnpm: Package manager for the UI monorepo
- MongoDB: Database for storing games and user data
- Redis: Used for WebSocket communication and caching
Optional
- git: For version control
- nginx: For proxying HTTP requests (production-like setup)
Installation Steps
Running Lichess Locally
Start the Server
Development Workflow
In the sbt console, you have access to various commands:
The server supports hot reloading. When you modify Scala files, sbt will automatically detect changes and recompile when you save.
UI Development
For frontend development, build the UI assets in watch mode:
This continuously rebuilds when changes are detected. See UI Development for more details.
Troubleshooting
JVM Memory Issues
If you encounter out-of-memory errors, adjust the settings in .sbtopts:
Port Already in Use
If port 9663 is already in use, you can change it in conf/application.conf:
MongoDB Connection Failed
Verify MongoDB is running:
Node.js Version Mismatch
The ui/build script checks for the minimum required Node.js version. If you see an error, upgrade Node.js:
Next Steps
Additional Resources
