lila-docker

Lichess development environment using Docker Compose, for developing on Mac, Linux, or Windows (via WSL).

The only requirements for running on your local machine are git and Docker Desktop. All the other dependencies (Scala, MongoDB, Node.js, etc) are installed and run in Docker containers.

Running in Gitpod

As an alternative to running it on your local machine, you can use Gitpod (a free, online, VS Code-like IDE) for contributing. With a single click, it will launch a workspace and automatically:

• Clone the necessary Lichess repositories
• Install all the dependencies
• Seed your database with test data
• Start your development site

Click here to create a workspace:

Also, see gitpod-prebuilds.md for more information on how to use prebuilds to speed up your development.

Instructions

1. Install Docker Desktop and have it running

2. Clone this repo:

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

3. Start the services

   cd lila-docker
   ./lila-docker start

   Starting new services may take 5-10 minutes. Some services will start before others and you may see errors in the logs until everything comes online.

   Lila will be the last service to complete, at which point you can visit http://localhost:8080/ to see the site.

Stopping

To stop the containers, for later resuming via ./lila-docker start:

./lila-docker stop

To remove the containers:

./lila-docker down

Adding a new service

To add a new optional service after the initial setup has already been done:

./lila-docker add-services

Select the service you want to add from the list of options.

NOTE: This will not affect the existing services, only the new ones among the selected services will be added.

URLs

Always available:

Service	URL
Main lila instance	http://localhost:8080/

Depending on which optional services you start:

Service	URL
Mongodb manager	http://localhost:8081/
Email inbox	http://localhost:8025/
lila-gif	http://localhost:6175/image.gif?fen=4k3/6KP/8/8/8/8/7p/8
Picfit	http://localhost:3001/healthcheck
Elasticsearch manager	http://localhost:8092/
lila-search docs	http://localhost:9673/docs/
API docs	http://localhost:8089/
Chessground	http://localhost:8090/demo.html
PGN Viewer	http://localhost:8091/
InfluxDB	http://localhost:8086/ (admin/password)

Usage

Scala development:

To restart lila (after making changes to any Scala code):

./lila-docker lila restart

UI (JS/CSS) development:

To watch for Typescript/SCSS changes and automatically recompile:

./lila-docker ui

Updating Routes

If you edit the conf/routes file, you'll need to update the route cache.

docker compose exec lila ./lila.sh playRoutes

To add translation keys:

After modifying a translation/source/*.xml file, run:

docker compose run --rm -w /lila ui pnpm run trans-dump

Code formatting:

./lila-docker format

Optional: Make the database persistent

docker compose cp mongodb:/data/db ./database

Then in docker-compose.ymladd - ./database:/data/db to mongodb volumes

Berserk (Python library):

To install the development version of Berserk and run a sample script against your local development site:

docker compose run --rm -w /berserk python sh -c "pip install -e . && python /scripts/berserk-example.py"
docker compose run --rm -w /berserk python sh -c "pip install -e . && python /scripts/berserk-connect-bots.py"

Scala Metals (IDE helper):

1. In VS Code, open this lila-docker project and install the Dev Containers extension
2. Cmd+Shift+P > "Dev Containers: Rebuild and Reopen in Container"
3. A new VS Code window will open, attached to the container instead of your host machine
4. File > Open Folder > "/workspaces/lila-docker/repos/lila" (or whichever Scala project you want to work on)
5. Install + Enable the Scala Metals extension (Cmd+Shift+X > "Scala (Metals)")
6. Cmd+Shift+P > "Metals: Import build"

Once the build has been imported, you should have code completion, go to definition, etc when you open a Scala file.

Scalachess:

If you're making changes to the Scalachess library, you can have lila use it instead of the published Maven version:

1. Update the build.sbt file in the scalachess repo:

   -  ThisBuild / version           := "15.6.7"
   +  ThisBuild / version           := "my-test-1"  # give it a custom version

2. Update the Dependencies.scala file in the lila repo:

   -  val chess = "org.lichess" %% "scalachess" % "15.6.7"
   +  val chess = "org.lichess" %% "scalachess" % "my-test-1"

3. Publish the local scalachess changes and restart lila:

   docker compose exec -w /scalachess lila sbt publishLocal
   docker compose restart lila

Other Scalachess commands:

## formatting
docker compose run --rm -w /scalachess --entrypoint="sbt check" lila
docker compose run --rm -w /scalachess --entrypoint="sbt prepare" lila

## compile
docker compose run --rm -w /scalachess --entrypoint="sbt compile" lila

## test
docker compose run --rm -w /scalachess --entrypoint="sbt testKit/test" lila

## package
docker compose run --rm -w /scalachess --entrypoint="sbt package" lila

Dartchess:

## run formatter
docker compose run --rm -w /dartchess mobile dart format .

## analyze
docker compose run --rm -w /dartchess mobile bash -c "dart pub get && dart analyze"

## run tests
docker compose run --rm -w /dartchess mobile bash -c "dart pub get && dart test -x full_perft"

Developing Chessground or PGN-Viewer locally

By default, your local lila instance will use the version of chessground + pgn-viewer that are published to npm. If you want to make changes to either library and see them reflected in your local lila instance, you can do the following:

1. Have lila use the local copy:

   docker compose run --rm -w /lila ui bash -c "pnpm link /chessground"
   
   docker compose run --rm ui bash -c "for dir in ui/bits ui/opening ui/site ui/tutor ui/common; do cd /lila/\$dir && pnpm link /pgn-viewer; done"

2. Start the compilers in watch mode:

   docker compose run --rm -w /chessground ui bash -c "pnpm install && pnpm run compile --watch"
   
   docker compose run --rm -w /pgn-viewer ui bash -c "pnpm install && pnpm run dist"

   See the updated chessground demo: http://localhost:8090/demo.html See the updated pgn-viewer demo: http://localhost:8091/

3. Start the lila ui build in watch mode:

   ./lila-docker ui

   and when you refresh lila, it will use the local copy of chessground and/or pgn-viewer.

InfluxDB Monitoring

To view the InfluxDB monitoring dashboard, start your environment with the Monitoring service enabled and then visit http://localhost:8086/ (admin/password)

You can also see all the metrics logged by running:

curl --get http://localhost:8086/query \
    --header "Authorization: Token secret" \
    --data-urlencode "db=kamon"  \
    --data-urlencode "q=show measurements;"

Mobile

Important

Requires Flutter and adb to be installed locally. Verify Flutter is configured correctly with flutter doctor.

1. On your Android phone:

   1. Connect your phone to the same wifi network as your host machine
   2. Enable Developer Mode
   3. In Developer Options, toggle Wireless Debugging to ON
   4. Tap "Wireless Debugging" to enter its menu

2. On your host machine:

   1. Have the lila-docker services running, with the Mobile optional service started

   2. Configure lila to run with your host's IP address or hostname instead of localhost

      ./lila-docker hostname

      • Then verify that your phone can access the site at http://[your-selection]:8080

   3. Connect to your phone

      ./lila-docker mobile

   4. Verify your phone is listed

      adb devices

   5. Install the app dependencies and run the app:

      cd repos/mobile
      
      flutter channel beta
      flutter upgrade
      
      flutter pub get
      dart run build_runner build
      
      flutter run