0. WSL 2 und Docker Desktop einrichten

Installieren Sie WSL 2 und Ubuntu und verbinden Sie Ubuntu anschließend mit Docker Desktop unter Windows.

Ayakaleaf Pro verwendet Linux-Container. Installieren Sie unter Windows Docker Desktop mit seinem WSL 2-Backend und führen Sie die Toolkit-Skripte in Ubuntu aus.

WSL 2 stellt den Linux-Kernel bereit. Docker Desktop verwaltet die Docker-Engine in seiner eigenen Umgebung docker-desktop; durch Aktivieren von WSL Integration kann die Docker-CLI in Ubuntu mit dieser Engine kommunizieren. Das Toolkit startet dann die Anwendung, MongoDB und Redis als Container. Bei aktivierten Sandboxed Compiles verwendet die Anwendung den Docker-Socket der Engine, um für jede Kompilierung einen separaten TeX Live-Container zu starten. Sie benötigen keine Windows-Installationen von MongoDB, Redis oder TeX Live.

1. WSL 2 und Ubuntu installieren

   Öffnen Sie in Windows PowerShell als Administrator und führen Sie Folgendes aus:

   wsl --install -d Ubuntu
   

   Starten Sie Windows neu, wenn Sie dazu aufgefordert werden. Öffnen Sie Ubuntu über das Startmenü und legen Sie einen Linux-Benutzernamen und ein Passwort fest. Dies ist das Konto für sudo innerhalb von Ubuntu; es ist unabhängig von Ihrer Windows-Anmeldung.

   Aktualisieren Sie zurück in PowerShell WSL und prüfen Sie die Distribution:

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

   Die Zeile für Ubuntu muss VERSION 2 anzeigen. Wenn dort 1 steht, verwenden Sie den genauen Distributionsnamen aus der Liste:

   wsl --set-version Ubuntu 2
   

   Docker erfordert WSL 2.1.5 oder neuer; die WSL-Softwareversion aus wsl --version und die Spalte VERSION 2 der Distribution sind unterschiedliche Prüfungen. Wenn die Installation fehlschlägt, siehe Fehlerbehebung bei der Installation und die Installationsanleitung von Microsoft, und aktivieren Sie die Hardware-Virtualisierung im BIOS/UEFI, wenn WSL meldet, dass sie nicht verfügbar ist.

2. Docker Desktop installieren und starten

   Laden Sie Docker Desktop for Windows für Ihren Prozessor herunter und führen Sie das Installationsprogramm aus. Verwenden Sie das WSL 2-Backend, falls angeboten. Öffnen Sie Docker Desktop über das Windows-Startmenü und warten Sie, bis die Engine gestartet ist.

   Aktivieren Sie in Docker Desktop unter Settings → General die Option Use WSL 2 based engine, falls sie angezeigt wird. Aktivieren Sie unter Settings → Resources → WSL Integration die Integration für Ubuntu und wählen Sie dann Apply oder Apply & restart. Wenn Ubuntu nicht Ihre Standarddistribution ist, aktivieren Sie ausdrücklich den eigenen Schalter dafür.

   Wenn WSL Integration fehlt, prüfen Sie, ob Docker Desktop Linux containers verwendet. Siehe Dockers Anleitung zum WSL 2-Backend.

   Verwenden Sie für diese Anleitung die Integration von Docker Desktop. Die Installation einer zweiten Docker Engine mit apt install docker.io oder das Starten von dockerd innerhalb von Ubuntu erzeugt ein separates Setup und kann Konflikte verursachen. Wenn Sie bereits eine Engine in Ubuntu verwenden, folgen Sie vor dem Umstieg den Migrationshinweisen von Docker; bewahren Sie vorhandene Anwendungsdaten und Backups auf.

3. Docker aus Ubuntu heraus prüfen

   Öffnen Sie ein Ubuntu-Terminal. Führen Sie diese Befehle dort aus, ohne sudo:

   docker version
   docker compose version
   docker ps
   

   docker version muss sowohl Client als auch Server anzeigen. Eine leere Containerliste ist bei einer Neuinstallation normal. docker --version allein beweist nicht, dass die Engine läuft.

   Wenn docker nicht verfügbar ist oder keine Verbindung herstellen kann, öffnen Sie Ubuntu nach dem Übernehmen der WSL Integration erneut und prüfen Sie, ob Docker Desktop läuft. Siehe Fehlerbehebung.

4. Ressourcen und den Docker-Socket prüfen

   Prüfen Sie die für Docker sichtbaren Ressourcen:

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

   Für eine kleine lokale Instanz sind 4 CPUs und 8 GB für Docker verfügbarer Arbeitsspeicher ein empfohlener Ausgangspunkt, kein gemessenes Minimum. Lassen Sie auch genügend Arbeitsspeicher für Windows übrig. Beim WSL 2-Backend werden Ressourcenlimits über die WSL-Einstellungen verwaltet, nicht über die Ressourcen-Schieberegler von Docker Desktop wie auf dem Mac. Änderungen, die wsl --shutdown erfordern, unterbrechen alle laufenden WSL-Distributionen und Docker-Workloads; übernehmen Sie sie, bevor Sie die Instanz starten.

   Belassen Sie DOCKER_SOCKET_PATH=/var/run/docker.sock in der Toolkit-Konfiguration. Die Anwendung benötigt diesen Engine-Socket für Sandboxed Compiles. Ändern Sie seine Berechtigungen nicht auf 777, um Verbindungsfehler zu beheben; stellen Sie stattdessen die Integration von Docker Desktop wieder her.

​

Nächster Schritt

Sobald docker ps in Ubuntu funktioniert, fahren Sie mit 1. Toolkit herunterladen fort.