0. Configurare WSL 2 e Docker Desktop

Installa WSL 2 e Ubuntu, quindi collega Ubuntu a Docker Desktop su Windows.

Ayakaleaf Pro usa container Linux. Su Windows, installa Docker Desktop con il suo backend WSL 2 ed esegui gli script del Toolkit in Ubuntu.

WSL 2 fornisce il kernel Linux. Docker Desktop gestisce il motore Docker nel proprio ambiente docker-desktop; abilitare WSL Integration permette alla CLI di Docker in Ubuntu di comunicare con quel motore. Il Toolkit avvia quindi l’applicazione, MongoDB e Redis come container. Con le sandboxed compiles abilitate, l’applicazione usa il socket Docker del motore per avviare un container TeX Live separato per ogni compilazione. Non servono installazioni Windows di MongoDB, Redis o TeX Live.

1. Installare WSL 2 e Ubuntu

   Apri PowerShell come amministratore in Windows ed esegui:

   wsl --install -d Ubuntu
   

   Riavvia Windows se richiesto. Apri Ubuntu dal menu Start e crea un nome utente e una password Linux. Questo è l’account per sudo all’interno di Ubuntu; è separato dal tuo accesso a Windows.

   Tornato in PowerShell, aggiorna WSL e controlla la distribuzione:

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

   La riga di Ubuntu deve mostrare VERSION 2. Se mostra 1, usa il nome esatto della distribuzione indicato nell’elenco:

   wsl --set-version Ubuntu 2
   

   Docker richiede WSL 2.1.5 o successivo; la versione del software WSL indicata da wsl --version e la colonna VERSION 2 della distribuzione sono controlli diversi. Consulta la risoluzione dei problemi di installazione e le istruzioni di installazione di Microsoft se l’installazione non riesce, e abilita la virtualizzazione hardware nel BIOS/UEFI se WSL segnala che non è disponibile.

2. Installare e avviare Docker Desktop

   Scarica Docker Desktop for Windows per il tuo processore ed esegui il programma di installazione. Usa il backend WSL 2 se proposto. Apri Docker Desktop dal menu Start di Windows e attendi l’avvio del motore.

   In Settings → General di Docker Desktop, abilita Use WSL 2 based engine se l’opzione è presente. In Settings → Resources → WSL Integration, abilita l’integrazione per Ubuntu, quindi seleziona Apply o Apply & restart. Se Ubuntu non è la tua distribuzione predefinita, abilita esplicitamente il suo interruttore.

   Se WSL Integration manca, controlla che Docker Desktop usi i Linux containers. Consulta la guida di Docker sul backend WSL 2.

   Per questa guida usa l’integrazione di Docker Desktop. Installare un secondo Docker Engine con apt install docker.io o avviare dockerd all’interno di Ubuntu crea una configurazione separata e può causare conflitti. Se usi già un Engine in Ubuntu, segui le indicazioni di migrazione di Docker prima di cambiare; conserva i dati applicativi e i backup esistenti.

3. Controllare Docker da Ubuntu

   Apri un terminale Ubuntu. Esegui lì questi comandi, senza sudo:

   docker version
   docker compose version
   docker ps
   

   docker version deve mostrare sia Client sia Server. Un elenco di container vuoto è normale su una nuova installazione. docker --version da solo non dimostra che il motore sia in esecuzione.

   Se docker non è disponibile o non riesce a connettersi, riapri Ubuntu dopo aver applicato WSL Integration e controlla che Docker Desktop sia in esecuzione. Vedi Risoluzione dei problemi.

4. Controllare le risorse e il socket Docker

   Controlla le risorse visibili a Docker:

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

   Per una piccola istanza locale, 4 CPU e 8 GB di memoria disponibili per Docker sono un suggerimento di partenza, non un minimo misurato. Lascia memoria sufficiente anche a Windows. Con il backend WSL 2, i limiti delle risorse si gestiscono tramite le impostazioni di WSL, anziché con i cursori delle risorse di Docker Desktop come su Mac. Le modifiche che richiedono wsl --shutdown interrompono tutte le distribuzioni WSL e i carichi di lavoro Docker in esecuzione; applicale prima di avviare l’istanza.

   Lascia DOCKER_SOCKET_PATH=/var/run/docker.sock nella configurazione del Toolkit. L’applicazione ha bisogno di questo socket del motore per le sandboxed compiles. Non cambiarne i permessi in 777 per risolvere errori di connessione; ripristina invece l’integrazione di Docker Desktop.

​

Passaggio successivo

Quando docker ps funziona in Ubuntu, prosegui con 1. Scaricare il Toolkit.