Deploying Lila

Introduction

Lila is the open-source chess server that powers Lichess.org, one of the world’s most popular chess platforms. Written in Scala and running on the Play Framework, Lila provides a comprehensive chess experience including real-time games, correspondence play, puzzles, analysis, and tournaments.

Running your own Lila instance allows you to create a private chess community, customize the experience, or simply understand how a world-class chess platform operates. The codebase is extensive but well-documented, reflecting years of development serving millions of chess players.

Key highlights of Lila:

Real-Time Chess: Play live games with sub-second move transmission
Multiple Time Controls: Bullet, blitz, rapid, and classical games
Correspondence Chess: Untimed games playable over days or weeks
Tournaments: Swiss, Arena, and custom tournament formats
Puzzles: Tactical training from real game positions
Analysis Board: Deep analysis with Stockfish integration
Study Feature: Collaborative analysis and lesson creation
Rating System: Glicko-2 rating for competitive play
Teams and Clubs: Community features for groups
API Access: Comprehensive API for integrations
100% Free: No premium features or advertisements

This guide walks through deploying Lila on Klutch.sh using Docker.

Why Deploy Lila on Klutch.sh

Deploying Lila on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh builds Lila from your configuration. Push to GitHub, and your chess server deploys.

Persistent Storage: Attach persistent volumes for game databases and user data.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure play.

GitHub Integration: Connect your repository for automatic redeployments.

Scalable Resources: Lila requires significant resources; allocate based on expected users.

Environment Variable Management: Configure settings securely.

Custom Domains: Assign a custom domain for your chess community.

Always-On Availability: Your chess server remains accessible 24/7.

Prerequisites

Before deploying Lila on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Strong familiarity with Docker and containerization
MongoDB for game storage
Redis for caching and real-time features
Significant computational resources (Scala/JVM-based)
(Optional) Stockfish for analysis features
(Optional) A custom domain

Understanding Lila Architecture

Lila is a complex multi-component system:

Lila Core: Scala/Play Framework application handling web requests.

LilaWs: WebSocket server for real-time game communication.

Fishnet: Distributed analysis using Stockfish.

MongoDB: Primary database for games, users, and content.

Redis: Caching, sessions, and real-time data.

Elasticsearch: Optional full-text search.

Preparing Your Repository

Repository Structure

lila-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

FROM hseeberger/scala-sbt:17.0.2_1.6.2_2.13.8 AS builder

# Clone Lila
RUN git clone --depth 1 https://github.com/lichess-org/lila.git /lila
WORKDIR /lila

# Build Lila
RUN sbt compile

FROM eclipse-temurin:17-jre

WORKDIR /app

# Copy built application
COPY --from=builder /lila/target /app/target
COPY --from=builder /lila/conf /app/conf

# Environment configuration
ENV MONGO_URI=${MONGO_URI:-mongodb://localhost:27017}
ENV REDIS_HOST=${REDIS_HOST:-localhost}
ENV REDIS_PORT=${REDIS_PORT:-6379}

# Expose port
EXPOSE 9663

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
  CMD curl -f http://localhost:9663/ || exit 1

CMD ["java", "-jar", "/app/target/universal/stage/lib/lila.jar"]

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
target/

Environment Variables Reference

Variable	Required	Default	Description
`MONGO_URI`	Yes	-	MongoDB connection string
`REDIS_HOST`	Yes	localhost	Redis hostname
`REDIS_PORT`	No	6379	Redis port
`DOMAIN`	Yes	-	Primary domain for the site

Deploying Lila on Klutch.sh

Set Up MongoDB

Deploy MongoDB for storing games and user data. A replica set is recommended for production.

Set Up Redis

Deploy Redis for caching and real-time features.

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Lila deployment configuration"
git remote add origin https://github.com/yourusername/lila-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “lila” or “chess”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Lila repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 9663 (Lila’s default port)

Set Environment Variables

Add the following:

Variable	Value
`MONGO_URI`	Your MongoDB connection string
`REDIS_HOST`	Your Redis hostname
`DOMAIN`	Your domain

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
`/app/data`	50+ GB	Application data

Deploy Your Application

Click Deploy to start the build process. Build time will be significant due to Scala compilation.

Access Lila

Once deployment completes, access your chess server at https://your-app.klutch.sh.

Initial Configuration

Creating Admin Account

Set up administrator access:

Register a new account through the web interface
Elevate permissions through the database
Access admin features

Configuring Game Settings

Customize gameplay:

Configure time controls
Set up variants
Adjust rating parameters

Setting Up Tournaments

Enable competitive play:

Configure tournament types
Set up automatic tournaments
Create custom events

Production Considerations

Lila is designed to serve millions of users on Lichess. Running a smaller instance still requires careful configuration:

Memory: JVM requires significant heap allocation
CPU: Scala compilation and runtime need substantial CPU
Network: Real-time games require low latency
Database: MongoDB performance is critical

Troubleshooting

Build Failures

Ensure sufficient memory for SBT
Check Scala version compatibility
Review build logs carefully

Connection Issues

Verify MongoDB connection
Check Redis availability
Review network configuration

Performance Problems

Increase JVM heap size
Optimize MongoDB indexes
Scale resources appropriately

Additional Resources

Conclusion

Deploying Lila on Klutch.sh enables you to run your own chess server with the same codebase that powers Lichess. While the setup is complex, the result is a fully-featured chess platform for your community.

This deployment requires significant resources and expertise but rewards you with a world-class chess experience.