> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Vianmääritys

> Docker Desktop -integraation, MongoDB:n käynnistyksen, Windowsin localhost-yhteyden ja hiekkalaatikkokäännösten vianmääritys WSL 2:ssa.

Aja Toolkitin ja Dockerin komennot **Ubuntussa**, ellei niitä ole merkitty **PowerShell**-komennoiksi. Säilytä määritykset ja data vikoja selvittäessäsi.

### WSL tai Docker ilmoittaa, että virtualisointi ei ole käytettävissä

WSL 2 -taustajärjestelmä tarvitsee laitteistovirtualisoinnin ja **Virtual Machine Platform** -ominaisuuden, ei täyttä Hyper-V-ominaisuutta, jota Dockerin vaihtoehtoinen Hyper-V-taustajärjestelmä käyttää. Aloita näillä tarkistuksilla:

1. Tarkista Windowsin kohdasta **Task Manager → Performance → CPU**, että **Virtualization: Enabled**. Jos se on pois käytöstä, ota Intel VT-x/VMX tai AMD-V/SVM käyttöön BIOS/UEFI-asetuksissa tietokoneen valmistajan ohjeiden mukaisesti.
2. Tarkista Windowsin ominaisuudet **PowerShellissä järjestelmänvalvojana**:

```powershell theme={null}
Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
```

Jos tarvittavat ominaisuudet ovat pois käytöstä, ota ne käyttöön ja käynnistä Windows uudelleen ennen kuin yrität WSL:ää uudelleen:

```powershell theme={null}
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
```

3. Jos ominaisuudet ja BIOS-asetus ovat käytössä mutta virhe `0x80370102` jatkuu, tarkista **PowerShellissä järjestelmänvalvojana**:

```powershell theme={null}
bcdedit /enum | findstr -i hypervisorlaunchtype
```

Jos se ilmoittaa nimenomaisesti `Off`, palauta hypervisorin käynnistys ja käynnistä Windows uudelleen:

```powershell theme={null}
bcdedit /set hypervisorlaunchtype auto
```

4. Jos Windows itse toimii virtuaalikoneessa, ulomman hypervisorin on tarjottava **sisäkkäinen virtualisointi**. Pelkkä Windowsin valintaruudun käyttöönotto ei voi tarjota puuttuvia virtuaalisen suorittimen ominaisuuksia.

Noudata vastaavan virheen kohdalla [Microsoftin WSL-virheen 0x80370102 korjausohjetta](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#error-0x80370102-the-virtual-machine-could-not-be-started-because-a-required-feature-is-not-installed) ja [Dockerin virtualisoinnin vianmääritystä](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#docker-desktop-fails-due-to-virtualization-not-working). Nämä korjaukset muuttavat Windowsin ominaisuuksia tai käynnistysmäärityksiä; suorita vain ne, jotka liittyvät diagnoosiisi.

### Docker Desktop tarvitsee päivityksen tai ei pysty hakemaan imageja

Jos saat ilmoituksen **WSL update required**, suorita PowerShellissä `wsl --update`, käynnistä Windows uudelleen pyydettäessä ja avaa sitten Docker Desktop ja Ubuntu uudelleen. Jos Ubuntu-rivillä lukee edelleen WSL 1, muunna jakelu vaiheessa 0 kuvatulla tavalla.

Jos saat rekisterin aikakatkaisuja tai DNS-, välityspalvelin- tai varmennevirheitä, tarkista hakutulosteesta, mikä rekisteri tarkalleen epäonnistuu. Määritä Windowsin/Docker Desktopin välityspalvelin ja varmenteiden luottamus, jos verkkosi tarvitsee niitä; älä poista TLS-varmennusta käytöstä. Onnistunut GitHub-kloonaus ei todista, että Docker tavoittaa `ghcr.io`:n tai Docker Hubin. Katso [Docker Desktopin välityspalvelinasetukset](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies). Kun yhteys toimii, suorita `bin/up -d` uudelleen; määritettyjen imagenimien on pysyttävä johdonmukaisina.

### Docker ei ole käytettävissä Ubuntussa

Jos `docker`-komentoa ei löydy, avaa Docker Desktop Windowsissa, ota Ubuntu käyttöön kohdassa **Settings → Resources → WSL Integration**, ota muutos käyttöön ja avaa Ubuntu uudelleen. Tarkista jakelun nimi ja WSL-tila komennolla `wsl --list --verbose` **PowerShellissä**. Sen on käytettävä WSL 2:ta.

Jos asiakasohjelma on olemassa mutta ei tavoita daemonia, tarkista, että moottori on käynnistynyt kokonaan. Tarkastele komennon `docker context ls` tulostetta ja mahdollisia mukautettuja `DOCKER_HOST`/`DOCKER_CONTEXT`-asetuksia; etämoottori tai vanha Ubuntun Engine-socket ei ole tämän oppaan paikallinen Desktop-kokoonpano. Älä korjaa tätä asentamalla toista daemonia tai tekemällä socketista kaikille kirjoitettavaa.

### MongoDB ei käynnisty

`bin/up` alustaa MongoDB:n replica setin ennen sovelluksen käynnistämistä. Jos se pysähtyy kohtaan `Waiting for Mongo...`, tarkastele tietokantaa toisessa **Ubuntu**-päätteessä:

```bash theme={null}
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}}'
```

Jos `mongo` puuttuu ja tulosteessa näkyy imagen hakuvirhe, ratkaise ensin rekisterin käyttö tai levytila; tietokannan käynnistykseen ei ole vielä päästy. Kun syy on korjattu, suorita `bin/up -d` uudelleen.

| Havainto | Mitä tarkistaa |
| - | - |
| `OOMKilled=true` | Lisää WSL:n/Dockerin käytettävissä olevaa muistia tai vähennä muita kuormia ja yritä uudelleen |
| `No space left on device` | Tarkista Windows-isännän tallennustila, Ubuntun `df -h` ja Dockerin levynkäyttö; vapauta tilaa poistamatta elävää tietokantadataa |
| Käyttöoikeus- tai tallennusvirheet hakemistossa `/data/db` | Pidä `MONGO_DATA_PATH` Ubuntun Linux-tiedostojärjestelmässä. Tarkista todellinen bind-liitos ja omistajuus; älä käytä komentoa `chmod -R 777` |
| Illegal instruction / suorittimen ominaisuusvirheet | Tarkista, että suoritin ja virtualisointi tarjoavat MongoDB-versiosi vaatimat ominaisuudet; portin vaihtaminen ei korjaa tätä |
| Tietokannan muoto- tai päivitysvirheet olemassa olevan datan kanssa | Noudata tuettua [päivitysmenettelyä](https://ayakaleaf-pro.mintlify.site/fi/on-premises/maintenance/upgrading-your-deployment.md); älä osoita mielivaltaista vanhempaa MongoDB-imagea uudempaan dataan |

Kun MongoDB on käynnissä, tarkista replica set:

```bash theme={null}
bin/docker-compose exec -T mongo mongosh --quiet --eval 'rs.status().ok'
```

Tuloksen pitäisi olla `1`. `bin/up -d` tekee replica setin alkumäärityksen; Compose-palveluiden käynnistäminen suoraan uudessa käyttöönotossa ohittaa tämän Toolkitin vaiheen.

Käytä MongoDB:n ydinkiertotietä vain, jos Docker-moottorisi käyttää ongelmallista ydintä. Jos MongoDB:n lokit viittaavat ydinongelmaan, vertaa moottorin todellista ydintä [MongoDB:n tuotanto-ohjeisiin](https://www.mongodb.com/docs/manual/administration/production-notes/) ja päivitä WSL/Docker tarpeen mukaan. Älä koskaan tyhjennä hakemistoa `data/mongo` yleisenä käynnistyskorjauksena.

### Windows ei pysty avaamaan localhostia

Testaa ensin Ubuntussa:

```bash theme={null}
bin/docker-compose ps
bin/docker-compose port sharelatex 80
curl -I http://localhost:8080/launchpad
```

Testaa sitten **PowerShellissä**:

```powershell theme={null}
curl.exe -I http://localhost:8080/launchpad
```

Jos molemmat epäonnistuvat, tarkista sovelluksen lokit ja porttimääritykset. Jos vain Windows epäonnistuu, tarkista, käyttääkö jokin muu Windows-prosessi porttia 8080, sekä mukautetut WSL-verkkoasetukset, VPN-/välityspalvelinsäännöt ja tietoturvaohjelmistot. Älä poista palomuuria käytöstä yleisesti. Vaihdettu portti vaatii vastaavat `OVERLEAF_PORT`- ja `OVERLEAF_SITE_URL`-arvot sekä selaimen URL-osoitteen, minkä jälkeen suoritetaan `bin/up -d`.

### Hiekkalaatikkokäännökset epäonnistuvat

Varmista kaikki kolme osaa: image on olemassa tässä Docker-moottorissa, sovellus voi käyttää moottorin socketia ja rinnakkainen kontti voi liittää käännöshakemiston:

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

Käytä tiedostossa `config/variables.env` määritettyä imagea. `SERVER_PRO=true`, `SIBLING_CONTAINERS_ENABLED=true` ja `DOCKER_SOCKET_PATH=/var/run/docker.sock` kuuluvat tiedostoon `config/overleaf.rc`. Suorita muokkausten jälkeen `bin/up -d`; pelkkä `bin/start` ei päivitä kontin ympäristöä.

Virhe `No such image` tarkoittaa, ettei Docker löydä projektin pyytämää tarkkaa imagea. Pidä `TEX_LIVE_DOCKER_IMAGE` ja `ALL_TEX_LIVE_DOCKER_IMAGES` johdonmukaisina, hae image samaan moottoriin ja tarkista projektin TeX Live -valinta. Olemassa olevat projektit saattavat säilyttää vanhemman imagevalinnan.

Jos saat liitosvirheen tai `/compile`-hakemisto on tyhjä, varmista, että Toolkit on Ubuntun kotihakemiston alla ja että Docker Desktopin integraatio on käytössä samalle jakelulle. Älä korvaa WSL-isäntäpolkua Windowsin `C:\...`-polulla. Toolkit laskee rinnakkaisen kontin polun arvosta `OVERLEAF_DATA_PATH`.

Puuttuva `ctexart.cls` tai fontti **basic**-imagella on paketti- tai imagerajoitus. Varmista ensin yksinkertainen article [vaiheesta 6](https://ayakaleaf-pro.mintlify.site/fi/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md); käytä täydellisempää imagea projekteille, jotka tarvitsevat lisäpaketteja. Älä poista hiekkalaatikkoa käytöstä puuttuvan TeX-paketin korjaamiseksi.

### Komentotulkkiskriptit ilmoittavat CRLF-virheistä

Aja skriptit Ubuntun Bashissa. Muokkaa määrityksiä LF-rivinvaihdoilla. Virheet, joissa mainitaan `bash\r` tai `$'\r'`, tarkoittavat yleensä, että tiedostot on muunnettu Windowsin CRLF-muotoon. Palauta kyseinen skripti repositoriosta tai muunna sen rivinvaihdot säilyttäen paikalliset määritysmuutokset.

### Kontit katoavat uudelleenkäynnistyksen jälkeen

Tarkista, että Docker Desktop on käynnissä ja Ubuntun integraatio on käytössä. `docker ps` näyttää vain käynnissä olevat kontit; tarkastele myös komentoa `docker ps -a`. Jos moottori on eri kuin asennuksen aikana käytetty, vaihda takaisin oikeaan kontekstiin sen sijaan, että alustaisit uuden tyhjän asennuksen.

Jos kontit ovat olemassa mutta pysäytettyinä, suorita `bin/start` ja tarkastele lokeja. Noudata kohtaa [Pidä instanssi saatavilla](https://ayakaleaf-pro.mintlify.site/fi/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md#keep-the-instance-available) kirjautumisen yhteydessä tapahtuvan käynnistyksen, uudelleenkäynnistyskäytäntöjen ja Windowsin lepotila-asetusten osalta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.