Running your own lichess: what the lila codebase actually demands
Project brief: lichess.org: the forever free, adless and open source chess server .
At a glance
- What is it?
- lila is the Scala 3 server behind lichess.org, built for scale with MongoDB, Redis, Pekko streams and a separate WebSocket server. This review looks at what it takes to run it, where it hurts, and who should not try.
- Who is it for?
- Adopt lila if you are building a serious, real-time chess platform and can commit to a Scala 3 stack, a MongoDB cluster, Redis, a separate WebSocket service, and the AGPL-3.0 license. Do not adopt it if you want a small, single-binary server or a quick prototype, because the production architecture assumes distributed components and the setup wiki is the only real guide.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Scala, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What lila is and who it is for
lila is the server that runs lichess.org, described in the README as a free online chess game server focused on realtime gameplay and ease of use. It is written in Scala 3 and relies on a modified Play 2.8 framework. The target audience is not a single hobbyist hosting a small club site. It is an organization that wants to run a full chess platform with tournaments, simuls, forums, teams, a tactic trainer, and a shared analysis board. The feature list is broad, and each feature is baked into the same codebase. If you only need a simple game server, lila is overkill. If you need the full lichess feature set under your own control, this is the only codebase that gives it to you directly.
The architecture: async core, separate WebSocket, and a cluster for analysis
The README lays out a clear split of responsibilities. The main lila server is fully asynchronous, using Scala Futures and Pekko streams. WebSocket connections are not handled by the main server at all. They go to a separate server called lila-ws, which communicates with the main server using Redis. That is an important architectural decision: realtime play is isolated from the HTTP layer. Chess analysis is also separate. lila talks to Stockfish through fishnet, an AI cluster of donated servers. So a production deployment is not one process. It is at least lila, lila-ws, Redis, MongoDB, and a fishnet worker. The README also mentions nginx as a proxy for HTTP and WebSocket connections. The data layer is MongoDB, storing over 12 billion games, indexed by Elasticsearch. That scale informs every design choice. This is a server built for massive concurrent play, not for a small self-hosted instance.
Getting it running: lila.sh and the missing setup details
The README gives a short installation path. You run ./lila.sh, which is a thin wrapper around sbt, then run. That is the entire quick start. The README points to the wiki for a full development environment setup, specifically the Lichess Development Onboarding page. The actual configuration keys for MongoDB, Redis, or the WebSocket server are not in the README. You have to go to the wiki. That is a real gap for a first-time evaluator. The repository does show the project structure, but without the wiki you cannot know how to point lila at your own MongoDB instance or how to configure lila-ws. The supported browsers table is useful: Firefox 115+, Chromium 112+, Edge 111+, Opera 97+, and Safari 16.2+. Older browsers will not work. That is a concrete constraint for anyone serving a broad user base.
The real limitations: scale assumptions and operational burden
The biggest limitation is that lila is built for lichess.org's scale. The README mentions 12 billion games in MongoDB. That is not a design target you can ignore. The codebase assumes a distributed setup with Redis, a separate WebSocket server, and an external analysis cluster. Running all of that for a small community is possible but heavy. The modified Play 2.8 framework is another constraint. It is not stock Play. You inherit lichess's fork, which means you cannot assume standard Play documentation applies. The README warns that older browsers will not work, so your user base must be on recent browsers. There is no mention of a single-machine deployment mode or a lightweight configuration. If you want to run lila on one server, you will have to figure out how to run lila-ws and Redis alongside it, and the README does not tell you how. The wiki is the only source, and it is not part of this repository's documentation.
Alternatives: what else is out there and how it differs
The obvious alternative is to not run lila at all and instead build on a simpler chess engine library or a smaller server. For example, you could use scalachess, which is the pure chess logic submodule of lila, and write your own thin server. That gives you the rules and move validation without the full lila stack. The difference in approach is fundamental: lila is a complete platform with tournaments, forums, and analysis distribution, while scalachess is just the chess domain logic. Another alternative is to use a hosted chess API like the Lichess API itself, which the README explicitly invites: feel free to use the Lichess API in your applications. That way you get the features without hosting anything. The trade-off is control and data ownership. lila gives you the full server, but you pay for it with operational complexity. The API gives you ease, but you depend on lichess.org staying up and staying free.
Maintenance and upgrade cost, and license implications
The repository shows recent releases: v1.0.0 in January 2017 and v1.1.0 in August 2017. That is a sparse release history for a project that powers a major site, but the README describes continuous development with community translation and a competence development program for contributors. The maintenance cost is high because the stack is specialized. You need Scala 3 developers, familiarity with Play 2.8, Pekko streams, and MongoDB. The README mentions that lila uses a modified Play framework, which means upstream Play updates may not apply cleanly. Upgrading lila itself likely means tracking the master branch or the release tags, and the wiki is the only upgrade guide. The license is AGPL-3.0 or any later version at your choice. That is a strong copyleft license. If you modify lila and run it as a network service, you must make your modified source available to users. The README does not discuss commercial use, but the AGPL is known for that requirement. For a company that wants to keep its server code private, this is a hard stop. For a community project, it is fine.
What the README does not tell you, and why that matters
The README is short on operational details. It does not list the MongoDB schema, the Redis key structure, or how to configure lila-ws. It does not explain how to scale the analysis cluster. It does not mention backup procedures or monitoring. It does say that all rated games are published in a free PGN database, which implies a data export pipeline, but it does not say how to run that pipeline yourself. The production architecture section is dated July 2022 in the README, but the actual content of that section is empty in the cleaned material. So you cannot learn the production topology from this README. You have to rely on the wiki, the GitHub issues, and the Discord server. That is a real cost for an evaluator. You are not just adopting a codebase, you are adopting a community and its documentation ecosystem. The README also mentions browser testing with Browserstack and proxy detection with IP2Proxy, so those are external services you may need to replicate or replace.
Editorial conclusion
Adopt lila if you are building a serious, real-time chess platform and can commit to a Scala 3 stack, a MongoDB cluster, Redis, a separate WebSocket service, and the AGPL-3.0 license. Do not adopt it if you want a small, single-binary server or a quick prototype, because the production architecture assumes distributed components and the setup wiki is the only real guide. Before you start, verify that your team can maintain a modified Play 2.8 fork, that your deployment can run lila-ws alongside the main server, and that your game storage plan matches the 12-billion-game scale the project targets. The codebase is the actual lichess.org, so it is proven, but that proof comes with operational weight that most hobby projects will not want.
Community notes