Перейти до основного вмісту
Ayakaleaf Pro дає змогу виконувати компіляцію в захищеному ізольованому середовищі (sandbox) для корпоративного рівня безпеки. Для цього кожен проєкт запускається у власному захищеному середовищі Docker.

Підвищена безпека

Ізольована компіляція (Sandboxed Compiles) — рекомендований підхід для Ayakaleaf Pro, оскільки багато документів LaTeX потребують або мають змогу виконувати довільні shell-команди в процесі компіляції PDF. Якщо ви використовуєте ізольовану компіляцію, кожна компіляція виконується в окремому контейнері Docker з обмеженими можливостями, який не спільний з іншими користувачами чи проєктами та не має доступу до зовнішніх ресурсів, як-от мережа хоста.
Якщо ви спробуєте запустити Ayakaleaf Pro без ізольованої компіляції, компіляція виконуватиметься поряд з іншими одночасними компіляціями всередині основного контейнера Docker, і під час компіляції LaTeX користувачі матимуть повний доступ на читання й запис до ресурсів контейнера sharelatex (файлової системи, мережі та змінних середовища).

Простіше керування пакетами

Щоб не встановлювати пакети вручну, рекомендуємо ввімкнути ізольовану компіляцію. Це параметр Ayakaleaf 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.
Ізольована компіляція вимагає, щоб контейнер 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:
config/overleaf.rc
Щоб вимкнути їх, задайте SIBLING_CONTAINERS_ENABLED=false і виконайте bin/up. Тоді компіляції виконуються всередині контейнера sharelatex з його базовим TeX Live.

Для користувачів Docker Compose

Налаштування образу TexLive

Користувачі з материкового Китаю можуть завантажувати образи з дзеркала ghcr.nju.edu.cn, щоб пришвидшити завантаження, а потім присвоювати їм теги з назвою ghcr.io:
НЕ використовуйте ghcr.nju.edu.cn у налаштуваннях середовища toolkit: залиште там назви ghcr.io. Щоб bin/up не завантажував образи з ghcr.io повторно, встановіть SIBLING_CONTAINERS_PULL=false у config/overleaf.rc. Щоб підтримувати образи в актуальному стані через дзеркало, див. Автоматичне оновлення образів TeX Live Full.
Ayakaleaf Pro використовує три змінні середовища, щоб визначити, які образи TeX Live використовувати для ізольованої компіляції:
  • TEX_LIVE_DOCKER_IMAGE (необов’язкова) — образ TeX Live, який використовують нові проєкти. Він має бути одним з образів у ALL_TEX_LIVE_DOCKER_IMAGES. Якщо її не задано, нові проєкти використовують перший образ у ALL_TEX_LIVE_DOCKER_IMAGES.
  • ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (необов’язкова) — список назв образів, розділених комами, у тому самому порядку, що відображаються в налаштуваннях компілятора. Якщо її не задано або вона коротша за список образів, образ відображається за своїм тегом, наприклад 2026.1.
  • 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 ГБ вільного місця.
config/variables.env
Наполегливо рекомендується налаштувати щонайменше 2 образи texlive-full. Докладніше про причину див. #known-issues

Доступні образи 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. Але якщо ви справді хочете використовувати власний реєстр образів, додайте:
config/variables.env
Потім потрібно переконатися, що всі образи texlive знаходяться в your-repo, наприклад:
  • hub.your.com/your-repo/texlive-full:2025.1
  • hub.your.com/your-repo/texlive-full:2024.1
Докладніше — прочитайте наведений нижче вихідний код, щоб зрозуміти, як ми розбираємо ваші змінні середовища:
sandboxed-compiles/index.mjs

Автоматична синхронізація образів TeX Live

Щоб не оновлювати екземпляр вручну через bin/up щоразу, можна автоматизувати оновлення образу TeX Live. Див. updating-tex-live-full-images-automatically.md.

Відомі проблеми

Ось реальний випадок зі спільноти Overleaf:
Використовуючи 6.0.1-ext-v3.3, я маю такі налаштування у variables.env:
З texlive/texlive:latest-full це працює добре. Однак я завантажив інший образ texlive danteev/texlive:2025-10-15 і змінив обидві змінні на назву нового образу, але це не працює:
У журналах я бачу таке:
Схоже, що оновлені налаштування у variables.env не набувають чинності. Компіляція все ще намагається запустити образ texlive/texlive:latest-full, а не новий образ. Я пробував перезавантажити систему, видалити контейнери й запустити знову, але проблема та сама. Чи є якісь рішення?
Через певні технічні обмеження, якщо ви налаштуєте лише один образ Docker TeXLive, наприклад texlive-fullA:latest
і після певного часу роботи екземпляра Overleaf захочете змінити образ TeXLive на texlive-fullB:latest, то побачите, що ваші користувачі не можуть скомпілювати жоден проєкт.
Це тому, що назва образу TeXLive-Full (для ізольованої компіляції) кожного проєкту зберігається в базі даних. Назва образу в базі даних змінюється лише тоді, коли користувач перемикає версію TeXLive свого проєкту, наприклад з 2024 на 2025. Під час компіляції проєкту CLSI використовує назву образу контейнера, знайдену в базі даних, щоб безпосередньо скомпілювати проєкт. Якщо ви надаєте лише один образ Docker, користувачі не зможуть змінити образ, який використовується для компіляції проєкту. У такому разі потрібно написати скрипт, щоб вручну змінити образ TeXLive для всіх проєктів користувачів у MongoDB.

Налагодження та звітування

Виконайте таку команду, щоб переглянути журнал clsi через toolkit:
Якщо у вас виникли проблеми з компіляцією з образами TeX Live, створіть issue тут: https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml Щоб допомогти нам відтворити й діагностувати проблему, вас можуть попросити завантажити ваш проєкт в Overleaf. Після цього ми отримаємо проєкт і запустимо тести компіляції за допомогою GitHub Action.

Питання та відповіді

Відповідь: Контейнери й файли компіляції — так, із затримкою; образи TeX Live — ні.
  • Контейнери компіляції (project-<project id>-<hash>) повторно використовуються для компіляцій того самого проєкту, тож після компіляції вони залишаються. Щогодини виконується перевірка, яка видаляє ті, що старші за одну годину і проєкт яких не компілювався протягом останньої години. Зазвичай контейнер зникає через одну-дві години після останньої компіляції. Перезапуск Overleaf їх не видаляє; це робить наступна щогодинна перевірка.
  • Контейнери підрахунку слів, SyncTeX і конвертації видаляються одразу після завершення роботи.
  • Файли компіляції (data/overleaf/data/compiles і output) видаляються, коли проєкт не використовувався протягом одного дня; перевірка виконується кожні 10 хвилин. Коли на диску закінчується місце, цей період поступово скорочується до половини дня.
  • Образи TeX Live ніколи не видаляються, оскільки вони потрібні для кожної компіляції. Щоб звільнити місце після вилучення образу з ALL_TEX_LIVE_DOCKER_IMAGES, видаліть його командою docker image rm <image>.
Видаляти ці контейнери вручну не потрібно.
Відповідь: Ні. Кожен контейнер компіляції монтує лише каталог компіляції власного проєкту в /compile і не має доступу до мережі, а налаштування для монтування інших каталогів хоста в нього немає. Натомість завантажте потрібні проєкту файли в сам проєкт.
Відповідь: Так. ghcr.io/ayaka-notes/texlive-basic:<year>.1 (від 2020.1 до 2026.1) містить базову схему TeX Live і кілька пакетів, як-от latexmk, xetex і fontspec, без повного набору шрифтів. Він значно менший за texlive-full, але проєкти, що використовують інші пакети, отримуватимуть помилки про відсутні пакети. Для базового TeX Live 2025:
config/variables.env
ghcr.io/ayaka-notes/texlive-full:base не є базовим образом: він не містить TeX Live і не може компілювати.
Відповідь: Редактор цього не показує, а журнал clsi записує це лише на рівні debug. Проте кожен запит на компіляцію повертає цю інформацію: відкрийте інструменти розробника в браузері, перейдіть на вкладку Network, перекомпілюйте проєкт і виберіть запит compile. Його JSON-відповідь містить timings у мілісекундах, де compileE2E — це вся компіляція в сервісі компіляції, а compile — сам запуск LaTeX.
Останнє оновлення 13 листопада 2026 р.