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

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

> Діагностика інтеграції 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:

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

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

```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. Якщо компоненти та налаштування BIOS увімкнено, але помилка `0x80370102` не зникає, перевірте в **PowerShell від імені адміністратора**:

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

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

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

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

Для відповідної помилки скористайтеся [посібником Microsoft з виправлення помилки WSL 0x80370102](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) і [порадами Docker з усунення проблем віртуалізації](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#docker-desktop-fails-due-to-virtualization-not-working). Ці виправлення змінюють компоненти 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](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies). Щойно з'єднання запрацює, знову виконайте `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**:

```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` відсутній, а вивід показує помилку завантаження образу, спершу розв'яжіть проблему з доступом до реєстру або місцем на диску; до запуску бази даних справа ще не дійшла. Після усунення причини знову виконайте `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; зміна порту цього не виправить |
| Помилки формату бази даних / оновлення з наявними даними | Дотримуйтеся підтримуваної [процедури оновлення](https://ayakaleaf-pro.mintlify.site/uk/on-premises/maintenance/upgrading-your-deployment.md); не спрямовуйте довільний старіший образ MongoDB на новіші дані |

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

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

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

Застосовуйте обхідний шлях MongoDB для ядра лише тоді, коли ваш рушій Docker використовує уражене ядро. Якщо журнали MongoDB вказують на проблему з ядром, порівняйте фактичне ядро рушія з [примітками MongoDB щодо продакшн-середовища](https://www.mongodb.com/docs/manual/administration/production-notes/) і за потреби оновіть WSL/Docker. Ніколи не стирайте `data/mongo` як загальне виправлення проблем із запуском.

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

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

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

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

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

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

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

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

```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`. `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](https://ayakaleaf-pro.mintlify.site/uk/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md); для проєктів, яким потрібні додаткові пакети, використовуйте повніший образ. Не вимикайте ізоляцію, щоб виправити відсутній пакет TeX.

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

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

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

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

Якщо контейнери є, але зупинені, виконайте `bin/start` і перегляньте журнали. Про запуск під час входу, політики перезапуску та налаштування сплячого режиму Windows див. [Підтримання доступності екземпляра](https://ayakaleaf-pro.mintlify.site/uk/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md#keep-the-instance-available).


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