> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/uk/konfiguraciya/overleaf-toolkit/sandboxed-compiles.md). # Ізольовані компіляції Overleaf Pro постачається з можливістю запускати компіляції в захищеному пісочному середовищі для корпоративної безпеки. Це досягається шляхом запуску кожного проєкту у власному захищеному Docker-середовищі. ### Покращена безпека Sandboxed Compiles — це рекомендований підхід для Server Pro, оскільки багато документів LaTeX потребують/мають можливість виконувати довільні shell-команди як частину процесу компіляції PDF. Якщо ви використовуєте Sandboxed Compiles, кожна компіляція запускається в окремому Docker-контейнері з обмеженими можливостями, які не спільні з жодним іншим користувачем чи проєктом, і не має доступу до зовнішніх ресурсів, таких як мережева інфраструктура хоста. {% hint style="warning" %} Якщо ви спробуєте запустити Overleaf Pro **без** Sandboxed Compiles, компіляція виконується паралельно з іншими одночасними компіляціями всередині основного Docker-контейнера, і користувачі мають повний доступ на читання й запис до ресурсів `sharelatex` контейнера (файлова система, мережа та змінні середовища) під час запуску компіляцій LaTeX. {% endhint %} ### Простіше керування пакетами Щоб уникнути ручного встановлення пакетів, ми рекомендуємо увімкнути Sandboxed Compiles. Це налаштовуваний параметр у Server Pro, який надасть вашим користувачам доступ до того самого середовища TeX Live, що й на overleaf.com, але у вашій власній локальній інсталяції. Образи TeX Live, що використовуються Sandboxed Compiles, містять найпопулярніші пакети та шрифти, протестовані на наших шаблонах галереї, що забезпечує максимальну сумісність із локальними проєктами. Увімкнення Sandboxed Compiles дозволяє вам налаштувати, з яких версій TeX Live користувачі можуть обирати у своєму проєкті, а також встановити версію образу TeX Live за замовчуванням для нових проєктів. {% hint style="info" %} Якщо ви спробуєте запустити Overleaf Pro без Sandboxed Compiles, ваш екземпляр за замовчуванням використовуватиме базову схему версії TeX Live для компіляцій. Ця базова версія є легкою та містить лише дуже обмежений набір пакетів LaTeX, що, найімовірніше, призведе до помилок відсутніх пакетів у ваших користувачів, особливо якщо вони спробують використовувати готові шаблони. {% endhint %} Оскільки Overleaf Pro створено для роботи офлайн, не існує автоматичного способу інтегрувати шаблони галереї overleaf.com у вашу локальну інсталяцію; однак це можна зробити вручну для кожного шаблону окремо. Для отримання додаткової інформації про те, як це працює, перегляньте наш посібник із перенесення шаблонів з overleaf.com: [/pages/0da4c6a3906dd38224e377f81822ad623f327059#transferring-templates-from-overleaf.com](https://ayakaleaf-pro.ayaka.space/on-premises/uk/konfiguraciya/overleaf-toolkit/pages/0da4c6a3906dd38224e377f81822ad623f327059#transferring-templates-from-overleaf.com "mention"). {% hint style="info" %} Sandboxed Compiles вимагає, щоб `sharelatex` контейнер мав доступ до Docker socket на хост-машині (через bind mount), щоб він міг керувати цими сусідніми контейнерами для компіляції. {% endhint %} ## Як це працює Коли Sandboxed Compiles увімкнено, Docker socket буде змонтовано з хост-машини в `sharelatex` контейнер, щоб служба компілятора в контейнері могла створювати нові Docker-контейнери на хості. Потім для кожного запуску компілятора в кожному проєкті служба компіляції LaTeX (CLSI) виконуватиме таке: * Записати файли проєкту в розташування всередині `OVERLEAF_DATA_PATH`. * Використати змонтований Docker socket, щоб створити новий `texlive` контейнер для запуску компіляції. * Надати `texlive` контейнеру можливість читати дані проєкту з розташування під `OVERLEAF_DATA_PATH`. * Скомпілювати проєкт всередині `texlive` контейнера. ### Увімкнення Sandboxed Compiles #### Для користувачів Toolkit Щоб увімкнути sandboxed compiles (також відомі як сусідні контейнери), встановіть такі параметри конфігурації в `overleaf-toolkit/config/overleaf.rc`: {% code title="config/overleaf.rc" %} ```dotenv SERVER_PRO=true SIBLING_CONTAINERS_ENABLED=true ``` {% endcode %} #### Для користувачів Docker Compose {% hint style="danger" %} Починаючи з Overleaf CE/Server Pro `5.0.3` змінні середовища було перейменовано з `SHARELATEX_*` на `OVERLEAF_*`. {% endhint %} Якщо ви використовуєте `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 {% hint style="info" %} Для користувачів материкового Китаю ви можете використати `ghcr.nju.edu.cn` щоб пришвидшити завантаження. {% endhint %} Overleaf Pro використовує три змінні середовища, щоб визначити, які образи TeX Live використовувати для Sandboxed Compiles: * `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`. Під час запуску вашого екземпляра Overleaf Pro за допомогою `bin/up` команди Toolkit автоматично завантажить усі образи, перелічені в `ALL_TEX_LIVE_DOCKER_IMAGES`. Ось приклад, де ми використовуємо TeX Live 2025 за замовчуванням для нових проєктів і залишаємо 2024 для наявних проєктів. {% tabs %} {% tab title="типова інсталяція" %} Наведена нижче конфігурація встановлює всі повні Docker-образи TeX Live з 2025 до 2026 року. Перед використанням цієї конфігурації ми рекомендуємо мати щонайменше 80 ГБ доступного сховища. {% code title="config/variables.env" overflow="wrap" %} ```dotenv 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 ``` {% endcode %} {% endtab %} {% tab title="повна інсталяція" %} Наведена нижче конфігурація встановлює всі повні Docker-образи TeX Live з 2020 до 2026 року. Перед використанням цієї конфігурації ми рекомендуємо мати щонайменше 256 ГБ доступного сховища. {% code title="config/variables.env" overflow="wrap" %} ```dotenv 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 ``` {% endcode %} {% endtab %} {% endtabs %} {% hint style="danger" %} Настійно рекомендується встановити **щонайменше 2 образи texlive-full**. Для детальної причини дивіться [#known-issues](#known-issues "mention") {% endhint %} ### Доступні образи 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` {% hint style="warning" %} Існує сувора схема щодо того, як образи **мають** позначатися (застосовується такий регулярний вираз `^[0-9]+.[0-9]+` , де перше число визначає рік TeX Live, а друге — версію виправлення). {% endhint %} ### Чи можна використовувати інший реєстр образів > Дехто може запитати, чи можу я замінити `ghcr.io` іншим дзеркальним сайтом або переключити texlive на інший образ із Docker Hub? Ні, ми не рекомендуємо цього, оскільки конфігурація є відносно складною. Якщо ви завантажуєте з дзеркального сайту, ви можете перейменувати свій образ на `ghcr.io/ayaka-notes/texlive-full`. Але якщо ви справді хочете використовувати власний реєстр образів, додайте: {% code title="config/variables.env" overflow="wrap" %} ```dotenv IMAGE_ROOT=hub.your.com/your-repo ``` {% endcode %} Потім вам потрібно переконатися, що всі образи texlive знаходяться в `your-repo`, наприклад * `hub.your.com/your-repo/texlive-full:2025.1` * `hub.your.com/your-repo/texlive-full:2024.1` Для детальнішої інформації прочитайте вихідний код нижче, щоб зрозуміти, як ми обробляємо вашу змінну середовища: {% code title="sandboxed-compiles/index.mjs" overflow="wrap" expandable="true" %} ```mjs if (process.env.SANDBOXED_COMPILES === 'true') { // Встановити кореневий образ за замовчуванням, якщо не вказано let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes"; // Експортувати imageRoot до Settings Settings.imageRoot = imageRootPath // allowedImageNames має бути таким: // [ // { 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], })) // Зрештою, imageName буде об'єднано з imageRoot, щоб утворити повний шлях до образу // Повна назва буде виглядати так: ghcr.io/ayaka-notes/texlive-2023:latest // Встановити назву образу за замовчуванням, якщо не вказано if(!process.env.TEX_LIVE_DOCKER_IMAGE) { process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName } // Експортувати currentImageName до Settings // Це назва образу для нещодавно створених проєктів Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE } ``` {% endcode %} ### Відомі проблеми Це реальний випадок із спільноти Overleaf: > Використовуючи `6.0.1-ext-v3.3`, у мене є такі налаштування в `variables.env`: > > ```dotenv > 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 > TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15 > ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15 > ``` > > У журналах я бачу таке: > > {% code overflow="wrap" %} > > ``` > {"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 ... > ``` > > {% endcode %} > > Схоже, що оновлені налаштування в `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 (для sandbox compile) для кожного проєкту зберігається в базі даних. *Лише коли користувач перемикає версію TeXLive свого проєкту, наприклад з 2024 на 2025, назву образу буде змінено в базі даних*. Коли CLSI компілює проєкт, він використовує назву образу контейнера, знайдену в базі даних, щоб напряму скомпілювати проєкт. Якщо ви надаєте лише один Docker-образ, користувачі не зможуть змінити образ, що використовується для компіляції проєкту. У цьому випадку вам потрібно написати скрипт, щоб **вручну змінити** образ TeXLive для всіх проєктів користувачів у MongoDB. ### Налагодження Запустіть таку команду, щоб перевірити лог CLSI з toolkit: {% code overflow="wrap" %} ```bash bin/logs clsi ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ayakaleaf-pro.ayaka.space/on-premises/uk/konfiguraciya/overleaf-toolkit/sandboxed-compiles.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.