> ## 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. # Ізольована компіляція Ayakaleaf Pro дає змогу виконувати компіляцію в захищеному ізольованому середовищі (sandbox) для корпоративного рівня безпеки. Для цього кожен проєкт запускається у власному захищеному середовищі Docker. ### Підвищена безпека Ізольована компіляція (Sandboxed Compiles) — рекомендований підхід для Ayakaleaf Pro, оскільки багато документів LaTeX потребують або мають змогу виконувати довільні shell-команди в процесі компіляції PDF. Якщо ви використовуєте ізольовану компіляцію, кожна компіляція виконується в окремому контейнері Docker з обмеженими можливостями, який не спільний з іншими користувачами чи проєктами та не має доступу до зовнішніх ресурсів, як-от мережа хоста. Якщо ви спробуєте запустити Ayakaleaf Pro **без** ізольованої компіляції, компіляція виконуватиметься поряд з іншими одночасними компіляціями всередині основного контейнера Docker, і під час компіляції LaTeX користувачі матимуть повний доступ на читання й запис до ресурсів контейнера `sharelatex` (файлової системи, мережі та змінних середовища). ### Простіше керування пакетами Щоб не встановлювати пакети вручну, рекомендуємо ввімкнути ізольовану компіляцію. Це параметр Server Pro, який надає вашим користувачам доступ до того самого середовища TeX Live, що й на overleaf.com, але у вашій власній локальній інсталяції. Образи TeX Live, які використовуються для ізольованої компіляції, містять найпопулярніші пакети та шрифти, протестовані з шаблонами нашої галереї, що забезпечує максимальну сумісність для локальних проєктів. Увімкнення ізольованої компіляції дає змогу налаштувати, з яких версій TeX Live користувачі можуть обирати у своєму проєкті, а також задати версію образу TeX Live за замовчуванням для нових проєктів. Якщо ви спробуєте запустити Ayakaleaf Pro без ізольованої компіляції, ваш екземпляр за замовчуванням використовуватиме для компіляції базову схему TeX Live. Ця базова версія легка й містить лише дуже обмежений набір пакетів LaTeX, що, найімовірніше, призведе до помилок про відсутні пакети у ваших користувачів, особливо якщо вони намагатимуться використовувати готові шаблони. Оскільки Ayakaleaf Pro спроєктовано для роботи офлайн, автоматичного способу інтегрувати шаблони галереї overleaf.com у вашу локальну інсталяцію немає; проте це можна зробити вручну для кожного шаблону окремо. Докладніше про це див. у нашому посібнику з перенесення шаблонів з overleaf.com: [#transferring-templates-from-overleaf.com](/uk/on-premises/configuration/overleaf-toolkit/templates#transferring-templates-from-overleaf.com "mention"). Ізольована компіляція вимагає, щоб контейнер `sharelatex` мав доступ до сокета Docker на хост-машині (через bind mount), аби він міг керувати цими сусідніми контейнерами компіляції. ## Як це працює Коли ізольовану компіляцію ввімкнено, сокет Docker монтується з хост-машини в контейнер `sharelatex`, щоб сервіс компілятора в контейнері міг створювати нові контейнери Docker на хості. Потім для кожного запуску компілятора в кожному проєкті сервіс компілятора LaTeX (CLSI) виконує таке: * Записує файли проєкту в розташування всередині `OVERLEAF_DATA_PATH`. * Використовує змонтований сокет Docker, щоб створити новий контейнер `texlive` для цього запуску компіляції. * Контейнер `texlive` зчитує дані проєкту з розташування в `OVERLEAF_DATA_PATH`. * Компілює проєкт усередині контейнера `texlive`. ### Увімкнення ізольованої компіляції #### Для користувачів Toolkit Щоб увімкнути ізольовану компіляцію (також відому як Sibling containers), задайте такі параметри конфігурації в `overleaf-toolkit/config/overleaf.rc`: ```dotenv title="config/overleaf.rc" theme={null} SERVER_PRO=true SIBLING_CONTAINERS_ENABLED=true ``` #### Для користувачів Docker Compose Починаючи з Overleaf CE/Server Pro `5.0.3`, змінні середовища перейменовано з `SHARELATEX_*` на `OVERLEAF_*`. Якщо ви використовуєте версію `4.x` (або старішу), переконайтеся, що змінні мають відповідний префікс (наприклад, `SHARELATEX_MONGO_URL` замість `OVERLEAF_MONGO_URL`). ```yml theme={null} version: '2' services: sharelatex: #... volumes: - /data/overleaf_data:/var/lib/overleaf - /var/run/docker.sock:/var/run/docker.sock environment: #... DOCKER_RUNNER: "true" SANDBOXED_COMPILES: "true" SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles" #... #... ``` ### Налаштування образу TexLive Користувачі з материкового Китаю можуть замінити `ghcr.io` на `ghcr.nju.edu.cn`, щоб пришвидшити завантаження. Але **НЕ** використовуйте `ghcr.nju.edu.cn` безпосередньо в налаштуваннях середовища toolkit. Єдиним варіантом там має залишатися `ghcr.io`. Ayakaleaf Pro використовує три змінні середовища, щоб визначити, які образи TeX Live використовувати для ізольованої компіляції: * `TEX_LIVE_DOCKER_IMAGE` (обов'язкова) — образ TeX Live за замовчуванням для компіляції нових проєктів. Цей образ має бути включений до `ALL_TEX_LIVE_DOCKER_IMAGES`. * `ALL_TEX_LIVE_DOCKER_IMAGE_NAMES` (обов'язкова) — список зрозумілих назв образів, розділених комами, що використовуються як варіанти у фронтенді. * `ALL_TEX_LIVE_DOCKER_IMAGES` (обов'язкова) — список образів TeX Live для використання, розділених комами. Якщо для розгортання використовується Overleaf Toolkit, ці образи буде завантажено або оновлено. Щоб пропустити завантаження, встановіть `SIBLING_CONTAINERS_PULL=false` у `config/overleaf.rc`. Під час запуску екземпляра Ayakaleaf Pro командою `bin/up` Toolkit автоматично завантажить усі образи, перелічені в `ALL_TEX_LIVE_DOCKER_IMAGES`. Ось приклад, у якому для нових проєктів за замовчуванням використовується TeX Live 2026, а версія 2025 залишається для старих проєктів. Наведена конфігурація встановлює всі повні образи Docker TeX Live з 2025 по 2026 рік. Перед використанням цієї конфігурації рекомендуємо мати щонайменше **64 ГБ** вільного місця. ```dotenv title="config/variables.env" wrap theme={null} ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1, ghcr.io/ayaka-notes/texlive-full:2025.1 ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026, Texlive 2025 TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1 ``` Наведена конфігурація встановлює всі повні образи Docker TeX Live з 2020 по 2026 рік. Перед використанням цієї конфігурації рекомендуємо мати щонайменше **150 ГБ** вільного місця. ```dotenv title="config/variables.env" wrap theme={null} ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1,ghcr.io/ayaka-notes/texlive-full:2025.1,ghcr.io/ayaka-notes/texlive-full:2024.1,ghcr.io/ayaka-notes/texlive-full:2023.1,ghcr.io/ayaka-notes/texlive-full:2022.1,ghcr.io/ayaka-notes/texlive-full:2021.1,ghcr.io/ayaka-notes/texlive-full:2020.1 ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026,Texlive 2025,Texlive 2024,Texlive 2023,Texlive 2022,Texlive 2021,Texlive 2020 TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1 ``` Наполегливо рекомендується налаштувати **щонайменше 2 образи texlive-full**. Докладніше про причину див. [#known-issues](/uk/on-premises/configuration/overleaf-toolkit/sandboxed-compiles#known-issues "mention") ### Доступні образи TeX Live Це серія образів TeX Live, спеціально оптимізованих для Overleaf, які також можна додати до `TEX_LIVE_DOCKER_IMAGE` і `ALL_TEX_LIVE_DOCKER_IMAGES`: * `ghcr.io/ayaka-notes/texlive-full:2026.1` (також тег `latest`) * `ghcr.io/ayaka-notes/texlive-full:2025.1` * `ghcr.io/ayaka-notes/texlive-full:2024.1` * `ghcr.io/ayaka-notes/texlive-full:2023.1` * `ghcr.io/ayaka-notes/texlive-full:2022.1` * `ghcr.io/ayaka-notes/texlive-full:2021.1` * `ghcr.io/ayaka-notes/texlive-full:2020.1` Існує сувора схема того, як **мають** бути позначені теги образів (застосовується регулярний вираз `^[0-9]+.[0-9]+`, де перше число визначає рік TeX Live, а друге — версію патча). ### Чи можна використовувати інший реєстр образів > Дехто може запитати, чи можна замінити `ghcr.io` на інше дзеркало або перейти на інший образ texlive з Docker Hub? Ні, ми цього не рекомендуємо, оскільки конфігурація досить складна. Якщо ви завантажуєте образи з дзеркала, можете перейменувати свій образ на `ghcr.io/ayaka-notes/texlive-full`. Але якщо ви справді хочете використовувати власний реєстр образів, додайте: ```dotenv title="config/variables.env" wrap theme={null} IMAGE_ROOT=hub.your.com/your-repo ``` Потім потрібно переконатися, що всі образи texlive знаходяться в `your-repo`, наприклад: * `hub.your.com/your-repo/texlive-full:2025.1` * `hub.your.com/your-repo/texlive-full:2024.1` Докладніше — прочитайте наведений нижче вихідний код, щоб зрозуміти, як ми розбираємо ваші змінні середовища: ```mjs title="sandboxed-compiles/index.mjs" wrap expandable theme={null} if (process.env.SANDBOXED_COMPILES === 'true') { // Set default image root if not provided let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes"; // Export imageRoot to Settings Settings.imageRoot = imageRootPath // allowedImageNames should be: // [ // { imageName: "texlive-2023:latest", imageDesc: "TeX Live 2023" }, // { imageName: "texlive-2022:latest", imageDesc: "TeX Live 2022" }, // ] Settings.allowedImageNames = parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGES) .map((texImage, index) => ({ imageName: texImage.split("/")[texImage.split("/").length - 1], imageDesc: parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGE_NAMES)[index] || texImage.split(':')[1], })) // In the end, imageName will be put together with imageRoot to form the full image path // The full name will be like: ghcr.io/ayaka-notes/texlive-2023:latest // Set default image name if not provided if(!process.env.TEX_LIVE_DOCKER_IMAGE) { process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName } // Export currentImageName to Settings // This is the new created projects' image name Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE } ``` ### Автоматична синхронізація образів TeX Live Щоб не оновлювати екземпляр вручну через `bin/up` щоразу, можна автоматизувати оновлення образу TeX Live. Див. [updating-tex-live-full-images-automatically.md](/uk/on-premises/maintenance/updating-tex-live-full-images-automatically "mention"). ### Відомі проблеми Ось реальний випадок зі спільноти Overleaf: > Використовуючи `6.0.1-ext-v3.3`, я маю такі налаштування у `variables.env`: > > ```dotenv theme={null} > TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full > ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full > ``` > > З `texlive/texlive:latest-full` це працює добре. Однак я завантажив інший образ texlive `danteev/texlive:2025-10-15` і змінив обидві змінні на назву нового образу, але це не працює: > > ```dotenv theme={null} > TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15 > ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15 > ``` > > У журналах я бачу таке: > > ```text wrap theme={null} > {"name":"clsi","level":50,"err":{"message":"(HTTP code 404) no such container - No such image: texlive/texlive:latest-full ","name":"Error","stack":"Error: (HTTP code 404) no such container - No such image: texlive/texlive:latest-full ... > ``` > > Схоже, що оновлені налаштування у `variables.env` не набувають чинності. Компіляція все ще намагається запустити образ `texlive/texlive:latest-full`, а не новий образ. > > Я пробував перезавантажити систему, видалити контейнери й запустити знову, але проблема та сама. > > Чи є якісь рішення? Через певні технічні обмеження, якщо ви налаштуєте лише один образ Docker TeXLive, наприклад `texlive-fullA:latest` ```text theme={null} ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full ``` і після певного часу роботи екземпляра Overleaf захочете змінити образ TeXLive на `texlive-fullB:latest`, то побачите, що ваші користувачі не можуть скомпілювати жоден проєкт. ```text theme={null} ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full ``` Це тому, що назва образу TeXLive-Full (для ізольованої компіляції) кожного проєкту зберігається в базі даних. *Назва образу в базі даних змінюється лише тоді, коли користувач перемикає версію TeXLive свого проєкту, наприклад з 2024 на 2025*. Під час компіляції проєкту CLSI використовує назву образу контейнера, знайдену в базі даних, щоб безпосередньо скомпілювати проєкт. Якщо ви надаєте лише один образ Docker, користувачі не зможуть змінити образ, який використовується для компіляції проєкту. У такому разі потрібно написати скрипт, щоб **вручну змінити** образ TeXLive для всіх проєктів користувачів у MongoDB. ### Налагодження та звітування Виконайте таку команду, щоб переглянути журнал clsi через toolkit: ```bash wrap theme={null} bin/logs clsi ``` Якщо у вас виникли проблеми з компіляцією з образами TeX Live, створіть issue тут: [https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml](https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml) Щоб допомогти нам відтворити й діагностувати проблему, вас можуть попросити завантажити ваш проєкт в Overleaf. Після цього ми отримаємо проєкт і запустимо тести компіляції за допомогою GitHub Action. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.