Усунення несправностей

Діагностика інтеграції Docker Desktop, запуску MongoDB, доступу до localhost з Windows та ізольованої компіляції на WSL 2.

Виконуйте команди Toolkit і Docker в Ubuntu, якщо їх не позначено як PowerShell. Під час діагностики збоїв зберігайте конфігурацію та дані.

​

WSL або Docker повідомляє, що віртуалізація недоступна

Бекенду WSL 2 потрібні апаратна віртуалізація та Virtual Machine Platform, а не повний компонент Hyper-V, який використовує альтернативний бекенд Hyper-V у Docker. Почніть із таких перевірок:

1. У Windows відкрийте Task Manager → Performance → CPU і перевірте, що вказано Virtualization: Enabled. Якщо віртуалізацію вимкнено, увімкніть Intel VT-x/VMX або AMD-V/SVM у BIOS/UEFI згідно з інструкціями виробника вашого ПК.
2. У PowerShell від імені адміністратора перевірте компоненти Windows:

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

Якщо потрібні компоненти вимкнено, увімкніть їх і перезавантажте Windows, перш ніж знову пробувати WSL:

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

3. Якщо компоненти та налаштування BIOS увімкнено, але помилка 0x80370102 не зникає, перевірте в PowerShell від імені адміністратора:

bcdedit /enum | findstr -i hypervisorlaunchtype

Якщо команда явно повідомляє Off, відновіть запуск гіпервізора й перезавантажте Windows:

bcdedit /set hypervisorlaunchtype auto

4. Якщо сама Windows працює у віртуальній машині, зовнішній гіпервізор має надавати вкладену віртуалізацію (nested virtualization). Сам лише прапорець у Windows не може надати відсутні функції віртуального процесора.

Для відповідної помилки скористайтеся посібником Microsoft з виправлення помилки WSL 0x80370102 і порадами Docker з усунення проблем віртуалізації. Ці виправлення змінюють компоненти Windows або конфігурацію завантаження; виконуйте лише ті, що відповідають вашому діагнозу.

​

Docker Desktop потребує оновлення або не може завантажити образи

Якщо з’являється WSL update required, виконайте wsl --update у PowerShell, перезавантажте Windows, якщо буде запит, а потім знову відкрийте Docker Desktop і Ubuntu. Якщо в рядку Ubuntu досі вказано WSL 1, перетворіть дистрибутив, як описано в кроці 0.

У разі тайм-аутів реєстру, помилок DNS, проксі чи сертифікатів перевірте у виводі завантаження, який саме реєстр не відповідає. Налаштуйте проксі та довіру до сертифікатів у Windows/Docker Desktop, якщо цього потребує ваша мережа; не вимикайте перевірку TLS. Успішне клонування з GitHub не доводить, що Docker може дістатися до ghcr.io чи Docker Hub. Див. налаштування проксі Docker Desktop. Щойно з’єднання запрацює, знову виконайте bin/up -d; налаштовані назви образів мають залишатися узгодженими.

​

Docker недоступний в Ubuntu

Якщо docker не знайдено, відкрийте Docker Desktop у Windows, увімкніть Ubuntu в Settings → Resources → WSL Integration, застосуйте зміну й знову відкрийте Ubuntu. Перевірте назву дистрибутива та режим WSL за допомогою wsl --list --verbose у PowerShell. Дистрибутив має використовувати WSL 2.

Якщо клієнт є, але не може дістатися до демона, перевірте, чи рушій завершив запуск. Перегляньте docker context ls і будь-які власні налаштування DOCKER_HOST/DOCKER_CONTEXT; віддалений рушій або старий сокет Engine в Ubuntu — це не локальне налаштування Desktop із цього посібника. Не виправляйте це встановленням іншого демона чи наданням усім права запису до сокета.

​

MongoDB не запускається

bin/up ініціалізує набір реплік MongoDB перед запуском застосунку. Якщо він зупиняється на Waiting for Mongo..., перевірте базу даних у другому терміналі Ubuntu:

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 відсутній, а вивід показує помилку завантаження образу, спершу розв’яжіть проблему з доступом до реєстру або місцем на диску; до запуску бази даних справа ще не дійшла. Після усунення причини знову виконайте bin/up -d.

Ознака	Що перевірити
OOMKilled=true	Збільште пам’ять, доступну WSL/Docker, або зменште інші навантаження, а потім повторіть спробу
No space left on device	Перевірте сховище хоста Windows, df -h в Ubuntu і використання диска Docker; звільняйте місце, не видаляючи робочі дані бази даних
Помилки дозволів або сховища в /data/db	Тримайте MONGO_DATA_PATH у файловій системі Linux в Ubuntu. Перевірте фактичний bind mount і власника; не застосовуйте chmod -R 777
Помилки Illegal instruction / функцій процесора	Перевірте, що процесор і віртуалізація надають функції, потрібні вашій версії MongoDB; зміна порту цього не виправить
Помилки формату бази даних / оновлення з наявними даними	Дотримуйтеся підтримуваної процедури оновлення; не спрямовуйте довільний старіший образ MongoDB на новіші дані

Коли MongoDB працює, перевірте набір реплік:

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

Результат має бути 1. bin/up -d виконує початкове налаштування набору реплік; прямий запуск сервісів Compose у новому розгортанні пропускає цей крок Toolkit.

Застосовуйте обхідний шлях MongoDB для ядра лише тоді, коли ваш рушій Docker використовує уражене ядро. Якщо журнали MongoDB вказують на проблему з ядром, порівняйте фактичне ядро рушія з примітками MongoDB щодо продакшн-середовища і за потреби оновіть WSL/Docker. Ніколи не стирайте data/mongo як загальне виправлення проблем із запуском.

​

Windows не може відкрити localhost

Спершу перевірте в Ubuntu:

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

Потім перевірте в PowerShell:

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

Якщо обидві перевірки не вдаються, перегляньте журнали застосунку та конфігурацію порту. Якщо не вдається лише у Windows, перевірте, чи порт 8080 не використовує інший процес Windows, а також власні мережеві налаштування WSL, правила VPN/проксі чи захисне програмне забезпечення. Не вимикайте брандмауер глобально. Для зміненого порту потрібні відповідні OVERLEAF_PORT, OVERLEAF_SITE_URL і URL у браузері, а потім bin/up -d.

​

Ізольована компіляція не вдається

Перевірте всі три частини: образ існує в цьому рушії Docker, застосунок може використовувати сокет рушія, а сусідній контейнер може змонтувати каталог компіляції:

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. SERVER_PRO=true, SIBLING_CONTAINERS_ENABLED=true і DOCKER_SOCKET_PATH=/var/run/docker.sock належать до config/overleaf.rc. Після змін виконайте bin/up -d; сам лише bin/start не оновлює середовище контейнера.

Помилка No such image означає, що Docker не може знайти саме той образ, який запитує проєкт. Тримайте TEX_LIVE_DOCKER_IMAGE і ALL_TEX_LIVE_DOCKER_IMAGES узгодженими, завантажте образ у той самий рушій і перевірте вибір TeX Live у проєкті. Наявні проєкти можуть зберігати старіший вибір образу.

У разі помилки монтування або порожнього каталогу /compile переконайтеся, що Toolkit розташовано в домашньому каталозі Ubuntu, а інтеграцію Docker Desktop увімкнено саме для цього дистрибутива. Не замінюйте шлях хоста WSL шляхом Windows на кшталт C:\.... Toolkit обчислює шлях для сусіднього контейнера з OVERLEAF_DATA_PATH.

Відсутність ctexart.cls або шрифту в базовому образі — це обмеження пакетів/образу. Спершу перевірте просту статтю з кроку 6; для проєктів, яким потрібні додаткові пакети, використовуйте повніший образ. Не вимикайте ізоляцію, щоб виправити відсутній пакет TeX.

​

Скрипти оболонки повідомляють про помилки CRLF

Запускайте скрипти в Ubuntu Bash. Редагуйте конфігурацію із закінченнями рядків LF. Помилки, у яких згадується bash\r або $'\r', зазвичай означають, що файли було перетворено на формат Windows CRLF. Відновіть уражений скрипт з репозиторію або перетворіть його закінчення рядків, зберігши локальні зміни конфігурації.

​

Контейнери зникають після перезапуску

Перевірте, що Docker Desktop запущено, а інтеграцію з Ubuntu ввімкнено. docker ps показує лише запущені контейнери; перевірте також docker ps -a. Якщо рушій відрізняється від того, що використовувався під час налаштування, перемкніться назад на правильний контекст, а не ініціалізуйте ще одну порожню інсталяцію.

Якщо контейнери є, але зупинені, виконайте bin/start і перегляньте журнали. Про запуск під час входу, політики перезапуску та налаштування сплячого режиму Windows див. Підтримання доступності екземпляра.