> For the complete documentation index, see [llms.txt](https://overleaf-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://overleaf-pro.ayaka.space/on-premises/ru/konfiguraciya/overleaf-toolkit/kompilyacii-v-pesochnice.md). # Компиляции в песочнице Overleaf Pro поставляется с возможностью запускать компиляции в защищённой изолированной среде sandbox для корпоративной безопасности. Это достигается за счёт запуска каждого проекта в собственной защищённой 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/0683e8f90f7bf29520fd0eff04eceb7ce0c9e49f#transferring-templates-from-overleaf.com](https://overleaf-pro.ayaka.space/on-premises/ru/konfiguraciya/overleaf-toolkit/pages/0683e8f90f7bf29520fd0eff04eceb7ce0c9e49f#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 Чтобы включить изолированные компиляции (также известные как sibling containers), задайте следующие параметры конфигурации в `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 для существующих проектов. {% code title="config/variables.env" overflow="wrap" %} ```dotenv ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2025.1, ghcr.io/ayaka-notes/texlive-full:2024.1 ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2025, Texlive 2024 TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2025.1 ``` {% endcode %} {% 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:2025.1` (также `latest` тег) * `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 %} ### Известные проблемы > Использование `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-компиляции) в каждом проекте сохраняется в базе данных. *Только когда пользователь переключит версию 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://overleaf-pro.ayaka.space/on-premises/ru/konfiguraciya/overleaf-toolkit/kompilyacii-v-pesochnice.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.