lichess-org/lila: self-hosting the Lichess chess server

What lila actually is, and who the repository is for

Lila is the server code behind lichess.org, described in the README as "a free online chess game server focused on realtime gameplay and ease of use." The name is a contraction: li[chess in sca]la. It is not a chess library, not a bot, and not a client SDK. It is the application that serves games, tournaments, simuls, forums, teams, a tactic trainer, a shared analysis board and a game search engine.

The audience is narrow. You need Scala, an understanding of asynchronous server design, and a reason to run a chess platform yourself. The README points contributors at the wiki page "Lichess Development Onboarding" for a development environment, and at the GitHub issue tracker for bug reports and feature requests. If you want to play chess, the homepage is the product. If you want to study how a high-traffic realtime game server is assembled from MongoDB, Redis, Elasticsearch, Pekko streams and a separate WebSocket process, the repository is the interesting artifact.

One thing to settle before anything else: the last push to this repository was on 2017-08-31, and the most recent release listed is v1.1.0 on the same date. That is a long time ago. Treat the code as a historical snapshot of the architecture, not as a codebase that tracks the live site.

How the pieces fit: Pekko streams, a separate WebSocket server, and Redis in between

The README is unusually explicit about the data flow, and the split is the most instructive part of the design.

HTTP traffic is served by a modified Play 2.8 framework, with scalatags for templating. The server is described as fully asynchronous, making heavy use of Scala Futures and Pekko streams. Pure chess logic does not live here at all: it sits in the scalachess submodule, which keeps move generation and rule enforcement separate from the web tier.

WebSocket connections are handled by a separate server, lila-ws, which communicates over Redis. That separation is the key architectural decision. The main application does not hold the socket connections; it exchanges messages through Redis with a process whose only job is connection management. It means the socket tier can be scaled or restarted independently, and it also means Redis is on the critical path for every live game.

Persistence is MongoDB, which the README says stores more than 12 billion games, indexed by Elasticsearch. Computer analysis is not done in-process either: lila talks to Stockfish deployed in an AI cluster of donated servers, coordinated by fishnet. nginx can proxy both HTTP requests and WebSocket connections. The web client is TypeScript with snabbdom, and Sass generates the CSS.

Read that list again as a deployment checklist. A working instance needs MongoDB, Elasticsearch, Redis, a lila-ws process, nginx, and something to serve the compiled frontend. Each of those is a moving part that can fail on its own.

Starting lila locally: the thin wrapper and the run command

The README gives exactly two lines for installation. The first is a comment describing lila.sh as a thin wrapper around sbt; the second is the sbt command to start the server.

./lila.sh # thin wrapper around sbt
run

That is the whole documented install. There is no package manager step, no Dockerfile in the top-level listing, and no published artifact to pull. The repository does contain flake.nix and devenv.nix, so a Nix-based environment is part of the project's own tooling, but the README does not describe it and I will not guess at the commands.

The frontend is a separate concern. package.json declares pnpm as the package manager and pins the Node engine:

"engines": { "node": ">=24", "pnpm": "11" },
"packageManager": "[email protected]"

So a first real attempt means installing Node 24 or newer and pnpm 11, then running the sbt wrapper, and separately building the UI assets. The scripts block includes test, lint, format and a workspace-check entry, which tells you the project expects its own lint and format passes before a contribution lands. Expect the first run to fail on a missing database or Redis before it fails on anything chess-related. The README does not document a rollback or reset procedure for a half-initialised local instance.

The maintenance question the README does not answer

The repository is not archived, but the last push was on 2017-08-31. Both facts matter and they pull in opposite directions. Not archived means the project has not formally declared the code dead. A last push from 2017 means nobody has merged anything into this branch for roughly nine years, and the newest release listed is v1.1.0 from the same day.

For a reader deciding whether to build on lila, that gap is the whole decision. The README describes a stack that has moved on: Play 2.8, Scala 3, Pekko streams, TypeScript 7 in the dev dependencies, Node 24. A snapshot from 2017 cannot have been tested against any of the current versions of those dependencies, and the README's browser support table (Firefox 115+, Chromium 112+, Safari 16.2+) is clearly written for a much later state of the code than the last commit date suggests. The document and the commit history disagree, and you should trust the commit history.

There is also a governance layer. The top-level listing includes AI_POLICY.md, CONTRIBUTING.md and AGENTS.md, which suggests the project has opinions about how contributions, including automated ones, are made. The README itself mentions a competence development program that covers training costs for contributors. These are signals of an organised project, not of an abandoned one, which makes the stale branch harder to read rather than easier.

Where lila is the wrong tool

If you want to run a chess server for a club, a classroom or a small community, lila is the wrong starting point. The dependency surface alone (MongoDB, Elasticsearch, Redis, a separate WebSocket process, nginx, an AI cluster for analysis) is sized for a site with millions of games, not for thirty players on a Tuesday evening.

The second failure mode is subtler. The README's feature list reads like a product description, and it is easy to assume the repository is a complete, runnable copy of lichess.org. It is one repository in a set: the README explicitly says "See lichess.org/source for a list of repositories." Chess logic lives in scalachess, the WebSocket server lives in lila-ws, and the analysis workers live in fishnet. Cloning lila alone gives you the application tier and nothing that satisfies its external dependencies.

The third case is licensing. AGPL-3.0 is a strong copyleft licence with a network clause. If you modify lila and let users interact with it over a network, the licence's terms reach that modified version. That is a deliberate fit for a project whose homepage calls itself "forever free, adless and open source," and it is a poor fit for anyone planning a closed derivative. I am describing the licence text, not giving legal advice; read COPYING.md and LICENSE yourself.

What a smaller alternative looks like

The realistic alternative is not another full chess platform. It is a small server built on a chess library plus a WebSocket layer, where you own the game loop and nothing else. The difference in approach is the direction of the dependency: lila is an application that consumes a chess library (scalachess) and a socket server (lila-ws), while a small server is a thin wrapper that you write around a library and a socket framework you already know.

That trade is real. You give up the search engine, the tournament system, the tactic trainer, the shared analysis board and the 140-plus translations that the README credits to the Crowdin community. You gain a process you can read end to end in an afternoon, a database you can back up with a file copy, and no Elasticsearch cluster. For most self-hosting scenarios the second option wins on operability alone.

The honest case for lila is the opposite one. If your goal is to understand how a realtime chess platform survives load, the split between the application and lila-ws, the Redis message bus, and the decision to push analysis to donated workers are all worth reading in the original. That is a study use, not an operations use.

Licence and upgrade cost before you commit

Lila is licensed under the GNU Affero General Public License 3 or any later version at your choice, per the README, with details in COPYING.md. The network clause is the part that matters for a hosted instance: users interacting with your modified version over a network are covered by the licence's source-distribution terms. A private fork you never expose is a different situation from a public server. Read the licence text and COPYING.md rather than a summary.

The upgrade cost is the harder number to estimate, and the repository gives you a blunt signal: the last push was on 2017-08-31 and the newest release is v1.1.0 from that same day. There is no documented upgrade path in the README, no migration guide, and no changelog beyond the two releases listed. If you fork this, you are adopting the maintenance yourself, including the work of moving Play, Scala, Pekko, MongoDB and the frontend toolchain forward. The presence of .scala-steward.conf suggests dependency updates were once automated, but automation config in a repository that has not been pushed to since 2017 is a plan, not a result.

Editorial conclusion

Read the repository as a reference implementation of a realtime chess server, not as a product you deploy. Verify the last push date, the AGPL-3.0 obligations in COPYING.md, and whether the development onboarding wiki still matches the current build.sbt before you spend a week on it.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes