> ## 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.

# Sorun giderme

> WSL 2 üzerinde Docker Desktop entegrasyonu, MongoDB başlatma, Windows localhost erişimi ve korumalı alan derlemeleriyle ilgili sorunları teşhis edin.

**PowerShell** olarak işaretlenmedikçe Toolkit ve Docker komutlarını **Ubuntu**'da çalıştırın. Hataları teşhis ederken yapılandırmayı ve verileri koruyun.

### WSL veya Docker sanallaştırmanın kullanılamadığını bildiriyor

WSL 2 arka ucu, Docker'ın alternatif Hyper-V arka ucunun kullandığı tam Hyper-V özelliğine değil, donanım sanallaştırmasına ve **Virtual Machine Platform** özelliğine ihtiyaç duyar. Şu kontrollerle başlayın:

1. Windows **Task Manager → Performance → CPU** içinde **Virtualization: Enabled** değerini kontrol edin. Devre dışıysa bilgisayar üreticinizin talimatlarını izleyerek BIOS/UEFI'de Intel VT-x/VMX veya AMD-V/SVM'yi etkinleştirin.
2. **Yönetici olarak PowerShell**'de Windows özelliklerini kontrol edin:

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

Gerekli özellikler devre dışıysa WSL'yi yeniden denemeden önce bunları etkinleştirin ve Windows'u yeniden başlatın:

```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. Özellikler ve BIOS ayarı etkin olduğu halde `0x80370102` hatası devam ediyorsa **yönetici olarak PowerShell**'de kontrol edin:

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

Açıkça `Off` bildiriyorsa hipervizör başlatmayı geri yükleyin ve Windows'u yeniden başlatın:

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

4. Windows'un kendisi bir sanal makinede çalışıyorsa dıştaki hipervizörün **iç içe sanallaştırmayı (nested virtualization)** sunması gerekir. Yalnızca bir Windows onay kutusunu etkinleştirmek eksik sanal CPU özelliklerini sağlayamaz.

İlgili hata için [Microsoft'un WSL 0x80370102 hatası onarım kılavuzunu](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) ve [Docker'ın sanallaştırma sorun giderme belgelerini](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#docker-desktop-fails-due-to-virtualization-not-working) izleyin. Bu onarımlar Windows özelliklerini veya önyükleme yapılandırmasını değiştirir; yalnızca teşhisinizle ilgili olanları çalıştırın.

### Docker Desktop güncelleme gerektiriyor veya imajları çekemiyor

**WSL update required** için PowerShell'de `wsl --update` çalıştırın, istenirse Windows'u yeniden başlatın, ardından Docker Desktop'ı ve Ubuntu'yu yeniden açın. Ubuntu satırı hâlâ WSL 1 gösteriyorsa dağıtımı 0. adımda açıklandığı gibi dönüştürün.

Kayıt defteri (registry) zaman aşımları, DNS, proxy veya sertifika hataları için çekme çıktısında tam olarak hangi kayıt defterinin başarısız olduğunu kontrol edin. Ağınız gerektiriyorsa Windows/Docker Desktop proxy'sini ve sertifika güvenini yapılandırın; TLS doğrulamasını devre dışı bırakmayın. Başarılı bir GitHub klonlaması, Docker'ın `ghcr.io` veya Docker Hub'a ulaşabildiğini kanıtlamaz. Bkz. [Docker Desktop proxy ayarları](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies). Bağlantı çalıştığında `bin/up -d` komutunu yeniden çalıştırın; yapılandırılmış imaj adları tutarlı kalmalıdır.

### Docker Ubuntu'da kullanılamıyor

`docker` bulunamıyorsa Windows'ta Docker Desktop'ı açın, **Settings → Resources → WSL Integration** altında Ubuntu'yu etkinleştirin, değişikliği uygulayın ve Ubuntu'yu yeniden açın. **PowerShell**'de `wsl --list --verbose` ile dağıtımın adını ve WSL modunu kontrol edin. WSL 2 kullanmalıdır.

İstemci mevcut ancak daemon'a ulaşamıyorsa motorun başlamayı tamamladığını kontrol edin. `docker context ls` çıktısını ve özel `DOCKER_HOST`/`DOCKER_CONTEXT` ayarlarını inceleyin; uzak bir motor veya eski bir Ubuntu Engine soketi bu kılavuzdaki yerel Desktop kurulumu değildir. Bunu başka bir daemon kurarak veya soketi herkes tarafından yazılabilir hale getirerek düzeltmeye çalışmayın.

### MongoDB başlamıyor

`bin/up`, uygulamayı başlatmadan önce MongoDB replika kümesini başlatır. `Waiting for Mongo...` noktasında durursa veritabanını ikinci bir **Ubuntu** terminalinde inceleyin:

```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}}'
```

`mongo` yoksa ve çıktı bir imaj çekme hatası gösteriyorsa önce kayıt defteri erişimini veya disk alanı sorununu çözün; veritabanı başlatma aşamasına henüz gelinmemiştir. Neden giderildikten sonra `bin/up -d` komutunu yeniden çalıştırın.

| Belirti | Kontrol edilecekler |
| - | - |
| `OOMKilled=true` | WSL/Docker'a ayrılan belleği artırın veya diğer iş yüklerini azaltın, ardından yeniden deneyin |
| `No space left on device` | Windows ana bilgisayar depolamasını, Ubuntu'nun `df -h` çıktısını ve Docker'ın disk kullanımını kontrol edin; canlı veritabanı verilerini silmeden yer açın |
| `/data/db` altında izin veya depolama hataları | `MONGO_DATA_PATH` değerini Ubuntu'nun Linux dosya sisteminde tutun. Gerçek bind mount'u ve sahipliği kontrol edin; `chmod -R 777` uygulamayın |
| Illegal instruction / CPU özelliği hataları | CPU'nun ve sanallaştırmanın MongoDB sürümünüzün gerektirdiği özellikleri sunduğunu kontrol edin; portu değiştirmek bunu düzeltmez |
| Mevcut verilerle veritabanı biçimi / yükseltme hataları | Desteklenen [yükseltme prosedürünü](https://ayakaleaf-pro.mintlify.site/tr/on-premises/maintenance/upgrading-your-deployment.md) izleyin; daha yeni verilere rastgele eski bir MongoDB imajını yönlendirmeyin |

MongoDB çalışırken replika kümesini kontrol edin:

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

Sonuç `1` olmalıdır. `bin/up -d` ilk replika kümesi kurulumunu gerçekleştirir; yeni bir dağıtımda Compose hizmetlerini doğrudan başlatmak bu Toolkit adımını atlar.

Bir MongoDB çekirdek geçici çözümünü yalnızca Docker motorunuz etkilenen bir çekirdek kullanıyorsa uygulayın. MongoDB günlükleri bir çekirdek sorununa işaret ediyorsa motorun gerçek çekirdeğini [MongoDB'nin üretim notlarıyla](https://www.mongodb.com/docs/manual/administration/production-notes/) karşılaştırın ve WSL/Docker'ı uygun şekilde güncelleyin. Genel bir başlatma düzeltmesi olarak `data/mongo` dizinini asla silmeyin.

### Windows localhost'u açamıyor

Önce Ubuntu'da test edin:

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

Ardından **PowerShell**'de test edin:

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

Her ikisi de başarısız olursa uygulama günlüklerini ve port yapılandırmasını kontrol edin. Yalnızca Windows başarısız olursa 8080 portunu kullanan başka bir Windows işlemi, özel WSL ağ ayarları, VPN/proxy kuralları veya güvenlik yazılımı olup olmadığını kontrol edin. Güvenlik duvarını genel olarak devre dışı bırakmayın. Değiştirilmiş bir port; buna uygun `OVERLEAF_PORT`, `OVERLEAF_SITE_URL` ve tarayıcı URL'si ile ardından `bin/up -d` gerektirir.

### Korumalı alan derlemeleri başarısız oluyor

Üç bileşenin tümünü doğrulayın: imaj bu Docker motorunda mevcut olmalı, uygulama motor soketini kullanabilmeli ve kardeş (sibling) konteyner derleme dizinini bağlayabilmelidir:

```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
```

`config/variables.env` içinde yapılandırılmış imajı kullanın. `SERVER_PRO=true`, `SIBLING_CONTAINERS_ENABLED=true` ve `DOCKER_SOCKET_PATH=/var/run/docker.sock` ayarları `config/overleaf.rc` içinde yer alır. Düzenlemelerden sonra `bin/up -d` çalıştırın; tek başına `bin/start` konteyner ortamını güncellemez.

`No such image` hatası, Docker'ın o projenin istediği imajı tam olarak bulamadığı anlamına gelir. `TEX_LIVE_DOCKER_IMAGE` ve `ALL_TEX_LIVE_DOCKER_IMAGES` değerlerini tutarlı tutun, imajı aynı motorda çekin ve projenin TeX Live seçimini kontrol edin. Mevcut projeler daha eski bir imaj seçimini koruyor olabilir.

Bir bağlama hatası veya boş bir `/compile` dizini için Toolkit'in Ubuntu'nun ana dizini altında olduğunu ve Docker Desktop entegrasyonunun aynı dağıtım için etkinleştirildiğini doğrulayın. WSL ana bilgisayar yolunu bir Windows `C:\...` yoluyla değiştirmeyin. Toolkit, kardeş konteyner yolunu `OVERLEAF_DATA_PATH` değerinden hesaplar.

**basic** ile eksik bir `ctexart.cls` veya yazı tipi bir paket/imaj sınırlamasıdır. Önce [6. adımdaki](https://ayakaleaf-pro.mintlify.site/tr/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md) basit makaleyi doğrulayın; ek paketlere ihtiyaç duyan projeler için daha kapsamlı bir imaj kullanın. Eksik bir TeX paketini düzeltmek için korumalı alanı devre dışı bırakmayın.

### Kabuk betikleri CRLF hataları bildiriyor

Betikleri Ubuntu Bash'te çalıştırın. Yapılandırmayı LF satır sonlarıyla düzenleyin. `bash\r` veya `$'\r'` içeren hatalar genellikle dosyaların Windows CRLF biçimine dönüştürüldüğü anlamına gelir. Etkilenen betiği depodan geri yükleyin veya yerel yapılandırma değişikliklerini koruyarak satır sonlarını dönüştürün.

### Konteynerler yeniden başlatmadan sonra kayboluyor

Docker Desktop'ın çalıştığını ve Ubuntu entegrasyonunun etkin olduğunu kontrol edin. `docker ps` yalnızca çalışan konteynerleri gösterir; `docker ps -a` çıktısını da inceleyin. Motor, kurulum sırasında kullanılandan farklıysa başka bir boş kurulum başlatmak yerine doğru bağlama geri dönün.

Mevcut ancak durdurulmuş konteynerler için `bin/start` çalıştırın ve günlükleri inceleyin. Oturum açıldığında başlatma, yeniden başlatma ilkeleri ve Windows uyku ayarları için [Örneği erişilebilir tutun](https://ayakaleaf-pro.mintlify.site/tr/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md#keep-the-instance-available) bölümünü izleyin.


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