0. Setup WSL 2 and Docker Desktop

Install WSL 2 and Ubuntu, then connect Ubuntu to Docker Desktop on Windows.

Ayakaleaf Pro uses Linux containers. On Windows, install Docker Desktop with its WSL 2 backend and run the Toolkit scripts in Ubuntu.

WSL 2 provides the Linux kernel. Docker Desktop manages the Docker engine in its own docker-desktop environment; enabling WSL Integration lets the Docker CLI in Ubuntu talk to that engine. The Toolkit then starts the application, MongoDB and Redis as containers. With sandboxed compiles enabled, the application uses the engine’s Docker socket to start a separate TeX Live container for each compile. You do not need Windows installations of MongoDB, Redis or TeX Live.

1. Install WSL 2 and Ubuntu

   Open PowerShell as administrator in Windows and run:

   wsl --install -d Ubuntu
   

   Restart Windows if prompted. Open Ubuntu from the Start menu and create a Linux username and password. This is the account for sudo inside Ubuntu; it is separate from your Windows login.

   Back in PowerShell, update WSL and check the distribution:

   wsl --update
   wsl --version
   wsl --list --verbose
   

   The Ubuntu row must show VERSION 2. If it shows 1, use its exact distribution name from the list:

   wsl --set-version Ubuntu 2
   

   Docker requires WSL 2.1.5 or later; the WSL software version from wsl --version and the distribution’s VERSION 2 column are different checks. See installation troubleshooting and Microsoft’s installation instructions if installation fails, and enable hardware virtualization in BIOS/UEFI if WSL reports that it is unavailable.

2. Install and start Docker Desktop

   Download Docker Desktop for Windows for your processor and run the installer. Use the WSL 2 backend if offered. Open Docker Desktop from the Windows Start menu and wait for the engine to start.

   In Docker Desktop Settings → General, enable Use WSL 2 based engine if the option is shown. Under Settings → Resources → WSL Integration, enable integration for Ubuntu, then select Apply or Apply & restart. If Ubuntu is not your default distribution, enable its own switch explicitly.

   If WSL Integration is missing, check that Docker Desktop is using Linux containers. See Docker’s WSL 2 backend guide.

   Use Docker Desktop’s integration for this guide. Installing a second Docker Engine with apt install docker.io or starting dockerd inside Ubuntu creates a separate setup and can cause conflicts. If you already use an Engine in Ubuntu, follow Docker’s migration guidance before switching; keep existing application data and backups.

3. Check Docker from Ubuntu

   Open an Ubuntu terminal. Run these commands there, without sudo:

   docker version
   docker compose version
   docker ps
   

   docker version must show both Client and Server. An empty container list is normal on a new installation. docker --version alone does not prove that the engine is running.

   If docker is unavailable or cannot connect, reopen Ubuntu after applying WSL Integration and check that Docker Desktop is running. See Troubleshooting.

4. Check resources and the Docker socket

   Check the resources visible to Docker:

   docker info --format 'CPUs={{.NCPU}} Memory={{.MemTotal}} Kernel={{.KernelVersion}}'
   df -h "$HOME"
   ls -l /var/run/docker.sock
   

   For a small local instance, 4 CPUs and 8 GB of memory available to Docker are a starting suggestion, not a measured minimum. Keep enough memory for Windows too. With the WSL 2 backend, resource limits are managed through WSL settings, rather than the Mac’s Docker Desktop resource sliders. Changes that require wsl --shutdown interrupt all running WSL distributions and Docker workloads; apply them before starting the instance.

   Leave DOCKER_SOCKET_PATH=/var/run/docker.sock in the Toolkit configuration. The application needs this engine socket for sandboxed compiles. Do not change its permissions to 777 to fix connection errors; restore Docker Desktop’s integration instead.

​

Next step

Once docker ps works in Ubuntu, continue with 1. Download the Toolkit.