Probleemoplossing

Diagnosticeer de integratie van Docker Desktop, het opstarten van MongoDB, toegang tot localhost vanuit Windows en sandbox-compilaties op WSL 2.

Voer Toolkit- en Docker-commando’s uit in Ubuntu, tenzij ze zijn gemarkeerd met PowerShell. Behoud de configuratie en gegevens terwijl je fouten diagnosticeert.

​

WSL of Docker meldt dat virtualisatie niet beschikbaar is

De WSL 2-backend heeft hardwarevirtualisatie en Virtual Machine Platform nodig, niet de volledige Hyper-V-functie die door de alternatieve Hyper-V-backend van Docker wordt gebruikt. Begin met deze controles:

1. Controleer in Windows onder Taakbeheer → Prestaties → CPU of Virtualisatie: Ingeschakeld wordt getoond. Als die is uitgeschakeld, schakel dan Intel VT-x/VMX of AMD-V/SVM in BIOS/UEFI in volgens de instructies van de fabrikant van je pc.
2. Controleer in PowerShell als administrator de Windows-onderdelen:

Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

Als vereiste onderdelen zijn uitgeschakeld, schakel ze dan in en start Windows opnieuw op voordat je WSL opnieuw probeert:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

3. Als de onderdelen en de BIOS-instelling zijn ingeschakeld maar fout 0x80370102 blijft, controleer dan in PowerShell als administrator:

bcdedit /enum | findstr -i hypervisorlaunchtype

Als dit expliciet Off meldt, herstel dan het opstarten van de hypervisor en start Windows opnieuw op:

bcdedit /set hypervisorlaunchtype auto

4. Als Windows zelf in een VM draait, moet de buitenste hypervisor geneste virtualisatie beschikbaar stellen. Alleen een selectievakje in Windows inschakelen kan ontbrekende virtuele CPU-functies niet leveren.

Volg de herstelhandleiding van Microsoft voor WSL-fout 0x80370102 en de probleemoplossing van Docker voor virtualisatie voor de bijbehorende fout. Deze herstelacties wijzigen Windows-onderdelen of de opstartconfiguratie; voer alleen de acties uit die relevant zijn voor jouw diagnose.

​

Docker Desktop heeft een update nodig of kan geen images ophalen

Voer bij WSL update required wsl --update uit in PowerShell, start Windows opnieuw op als daarom wordt gevraagd, en open daarna Docker Desktop en Ubuntu opnieuw. Als de rij van Ubuntu nog steeds WSL 1 aangeeft, converteer de distributie dan zoals beschreven in stap 0.

Controleer bij time-outs van de registry, DNS-, proxy- of certificaatfouten welke registry precies faalt in de uitvoer van het ophalen. Configureer de proxy en het certificaatvertrouwen van Windows/Docker Desktop als je netwerk die nodig heeft; schakel TLS-verificatie niet uit. Een geslaagde GitHub-kloon bewijst niet dat Docker ghcr.io of Docker Hub kan bereiken. Zie de proxy-instellingen van Docker Desktop. Zodra de verbinding werkt, voer je bin/up -d opnieuw uit; de geconfigureerde imagenamen moeten consistent blijven.

​

Docker is niet beschikbaar in Ubuntu

Als docker niet wordt gevonden, open dan Docker Desktop in Windows, schakel Ubuntu in onder Settings → Resources → WSL Integration, pas de wijziging toe en open Ubuntu opnieuw. Controleer de naam en WSL-modus van de distributie met wsl --list --verbose in PowerShell. Die moet WSL 2 gebruiken.

Als de client bestaat maar de daemon niet kan bereiken, controleer dan of de engine volledig is gestart. Bekijk docker context ls en eventuele aangepaste DOCKER_HOST/DOCKER_CONTEXT-instellingen; een externe engine of een oude Engine-socket in Ubuntu is niet de lokale Desktop-opzet van deze handleiding. Los dit niet op door een andere daemon te installeren of de socket voor iedereen schrijfbaar te maken.

​

MongoDB start niet

bin/up initialiseert de replica set van MongoDB voordat de applicatie start. Als het stopt bij Waiting for Mongo..., bekijk dan de database in een tweede Ubuntu-terminal:

cd "$HOME/ayakaleaf-toolkit"
bin/docker-compose ps -a
bin/docker-compose logs --tail=150 mongo
docker inspect mongo --format 'Exit={{.State.ExitCode}} OOM={{.State.OOMKilled}} Error={{.State.Error}}'
docker info --format '{{.KernelVersion}}'

Als mongo ontbreekt en de uitvoer een fout bij het ophalen van de image toont, los dan eerst de toegang tot de registry of het gebrek aan schijfruimte op; het opstarten van de database is dan nog niet bereikt. Zodra de oorzaak is verholpen, voer je bin/up -d opnieuw uit.

Aanwijzing	Wat je controleert
OOMKilled=true	Vergroot het geheugen dat beschikbaar is voor WSL/Docker of verminder andere workloads, en probeer het daarna opnieuw
No space left on device	Controleer de opslag van de Windows-host, df -h in Ubuntu en het schijfgebruik van Docker; maak ruimte vrij zonder live databasegegevens te verwijderen
Rechten- of opslagfouten onder /data/db	Houd MONGO_DATA_PATH op het Linux-bestandssysteem van Ubuntu. Controleer de werkelijke bind-mount en het eigenaarschap; pas geen chmod -R 777 toe
Illegal instruction / fouten over CPU-functies	Controleer of de CPU en de virtualisatie de functies beschikbaar stellen die je MongoDB-versie vereist; de poort wijzigen lost dit niet op
Fouten over databaseformaat / upgrade met bestaande gegevens	Volg de ondersteunde upgradeprocedure; laat geen willekeurige oudere MongoDB-image naar nieuwere gegevens wijzen

Controleer de replica set wanneer MongoDB draait:

bin/docker-compose exec -T mongo mongosh --quiet --eval 'rs.status().ok'

Het resultaat moet 1 zijn. bin/up -d voert de initiële configuratie van de replica set uit; door Compose-services op een nieuwe deployment rechtstreeks te starten, sla je die stap van de Toolkit over.

Pas een MongoDB-kernelworkaround alleen toe als je Docker-engine een getroffen kernel gebruikt. Als de MongoDB-logs op een kernelprobleem wijzen, vergelijk dan de werkelijke kernel van de engine met de productienotities van MongoDB en werk WSL/Docker waar nodig bij. Wis data/mongo nooit als algemene oplossing voor opstartproblemen.

​

Windows kan localhost niet openen

Test eerst in Ubuntu:

bin/docker-compose ps
bin/docker-compose port sharelatex 80
curl -I http://localhost:8080/launchpad

Test daarna in PowerShell:

curl.exe -I http://localhost:8080/launchpad

Als beide mislukken, controleer dan de applicatielogs en de poortconfiguratie. Als alleen Windows mislukt, controleer dan of een ander Windows-proces poort 8080 gebruikt, of er aangepaste WSL-netwerkinstellingen, VPN-/proxyregels of beveiligingssoftware actief zijn. Schakel de firewall niet globaal uit. Een gewijzigde poort vereist overeenkomende waarden voor OVERLEAF_PORT, OVERLEAF_SITE_URL en de browser-URL, gevolgd door bin/up -d.

​

Sandbox-compilaties mislukken

Controleer alle drie de onderdelen: de image bestaat in deze Docker-engine, de applicatie kan de engine-socket gebruiken, en de sibling-container kan de compilatiemap mounten:

docker image inspect ghcr.io/ayaka-notes/texlive-basic:2026.1 --format '{{.Architecture}} {{.Id}}'
docker inspect sharelatex --format '{{json .Mounts}}'
bin/logs -f clsi

Gebruik de image die is geconfigureerd in config/variables.env. SERVER_PRO=true, SIBLING_CONTAINERS_ENABLED=true en DOCKER_SOCKET_PATH=/var/run/docker.sock horen in config/overleaf.rc. Voer na wijzigingen bin/up -d uit; bin/start alleen werkt de omgeving van de container niet bij.

Een No such image-fout betekent dat Docker de exacte image die dat project vraagt niet kan vinden. Houd TEX_LIVE_DOCKER_IMAGE en ALL_TEX_LIVE_DOCKER_IMAGES consistent, haal de image op in dezelfde engine en controleer de TeX Live-selectie van het project. Bestaande projecten kunnen een oudere imagekeuze behouden.

Controleer bij een mountfout of een lege /compile-map of de Toolkit onder de thuismap van Ubuntu staat en of de integratie van Docker Desktop voor diezelfde distributie is ingeschakeld. Vervang het WSL-hostpad niet door een Windows-pad C:\.... De Toolkit berekent het pad voor de sibling-container op basis van OVERLEAF_DATA_PATH.

Een ontbrekend ctexart.cls of lettertype bij basic is een beperking van het pakket/de image. Controleer eerst het eenvoudige artikel uit stap 6; gebruik een uitgebreidere image voor projecten die extra pakketten nodig hebben. Schakel sandboxing niet uit om een ontbrekend TeX-pakket op te lossen.

​

Shellscripts melden CRLF-fouten

Voer de scripts uit in Ubuntu Bash. Bewerk de configuratie met LF-regeleinden. Fouten die bash\r of $'\r' noemen, betekenen meestal dat bestanden zijn geconverteerd naar Windows-CRLF. Herstel het betreffende script uit de repository of converteer de regeleinden ervan, met behoud van lokale configuratiewijzigingen.

​

Containers verdwijnen na een herstart

Controleer of Docker Desktop draait en of de Ubuntu-integratie is ingeschakeld. docker ps toont alleen draaiende containers; bekijk ook docker ps -a. Als de engine een andere is dan die tijdens de installatie werd gebruikt, schakel dan terug naar de juiste context in plaats van nog een lege installatie te initialiseren.

Voer bij containers die aanwezig maar gestopt zijn bin/start uit en bekijk de logs. Volg De instantie beschikbaar houden voor opstarten bij aanmelding, restartbeleid en de slaapstandinstellingen van Windows.