Ізольована компіляція

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.

Ізольована компіляція вимагає, щоб контейнер 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

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

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 ГБ вільного місця.

config/variables.env

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 ГБ вільного місця.

config/variables.env

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

​

Доступні образи 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

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

Докладніше — прочитайте наведений нижче вихідний код, щоб зрозуміти, як ми розбираємо ваші змінні середовища:

sandboxed-compiles/index.mjs

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.

​

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

Ось реальний випадок зі спільноти Overleaf:

Використовуючи 6.0.1-ext-v3.3, я маю такі налаштування у variables.env:

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 і змінив обидві змінні на назву нового образу, але це не працює:

TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15
ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15

У журналах я бачу таке:

{"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

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, то побачите, що ваші користувачі не можуть скомпілювати жоден проєкт.

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:

bin/logs clsi

Якщо у вас виникли проблеми з компіляцією з образами TeX Live, створіть issue тут:

https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml

Щоб допомогти нам відтворити й діагностувати проблему, вас можуть попросити завантажити ваш проєкт в Overleaf. Після цього ми отримаємо проєкт і запустимо тести компіляції за допомогою GitHub Action.