Изолированная компиляция

Ayakaleaf Pro позволяет выполнять компиляцию в защищённой изолированной среде (песочнице), что обеспечивает безопасность корпоративного уровня. Для этого каждый проект запускается в собственной защищённой среде Docker.

​

Повышенная безопасность

Изолированная компиляция (Sandboxed Compiles) — рекомендуемый подход для Ayakaleaf Pro, поскольку многие документы LaTeX требуют (или имеют возможность) выполнения произвольных команд оболочки в процессе компиляции PDF. При использовании изолированной компиляции каждая компиляция выполняется в отдельном Docker-контейнере с ограниченными возможностями, который не используется совместно с другими пользователями или проектами и не имеет доступа к внешним ресурсам, таким как сеть хоста.

Если вы попытаетесь запустить Ayakaleaf Pro без изолированной компиляции, компиляция будет выполняться вместе с другими одновременными компиляциями внутри основного Docker-контейнера, и при компиляции LaTeX пользователи будут иметь полный доступ на чтение и запись к ресурсам контейнера sharelatex (файловой системе, сети и переменным окружения).

​

Упрощённое управление пакетами

Чтобы не устанавливать пакеты вручную, рекомендуем включить изолированную компиляцию. Это настраиваемый параметр Server Pro, который предоставит вашим пользователям доступ к той же среде TeX Live, что и на overleaf.com, но в рамках вашей собственной локальной установки. Образы TeX Live, используемые для изолированной компиляции, содержат самые популярные пакеты и шрифты, протестированные на шаблонах из нашей галереи, что обеспечивает максимальную совместимость локальных проектов.

Включение изолированной компиляции позволяет настроить, из каких версий TeX Live пользователи смогут выбирать в своих проектах, а также задать версию образа TeX Live по умолчанию для новых проектов.

Если вы попытаетесь запустить Ayakaleaf Pro без изолированной компиляции, ваш экземпляр по умолчанию будет использовать для компиляции версию TeX Live с базовой схемой (basic scheme). Эта базовая версия легковесна и содержит лишь очень ограниченный набор пакетов 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"
            #...
        #...

​

Настройка образа TeX Live

Пользователи из материкового Китая могут заменить 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.