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:

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:

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:

bcdedit /enum | findstr -i hypervisorlaunchtype

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

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 ve Docker’ın sanallaştırma sorun giderme belgelerini 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ı. 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:

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ü izleyin; daha yeni verilere rastgele eski bir MongoDB imajını yönlendirmeyin

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

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

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

Ardından PowerShell’de test edin:

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:

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 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 bölümünü izleyin.