Compilaciones aisladas

Ayakaleaf Pro ofrece la opción de ejecutar las compilaciones en un entorno aislado (sandbox) seguro para ofrecer seguridad de nivel empresarial. Para ello, ejecuta cada proyecto en su propio entorno de Docker seguro.

​

Mayor seguridad

Las compilaciones aisladas (Sandboxed Compiles) son el enfoque recomendado para Ayakaleaf Pro, ya que muchos documentos LaTeX requieren o tienen la capacidad de ejecutar comandos de shell arbitrarios como parte del proceso de compilación del PDF. Si usas compilaciones aisladas, cada compilación se ejecuta en un contenedor de Docker independiente con capacidades limitadas, que no se comparte con ningún otro usuario ni proyecto y que no tiene acceso a recursos externos como la red del host.

Si intentas ejecutar Ayakaleaf Pro sin compilaciones aisladas, la compilación se ejecuta junto con otras compilaciones simultáneas dentro del contenedor de Docker principal, y los usuarios tienen acceso completo de lectura y escritura a los recursos del contenedor sharelatex (sistema de archivos, red y variables de entorno) al ejecutar compilaciones de LaTeX.

​

Gestión de paquetes más sencilla

Para evitar instalar paquetes manualmente, recomendamos habilitar las compilaciones aisladas. Se trata de un ajuste configurable de Server Pro que proporciona a tus usuarios acceso al mismo entorno de TeX Live que en overleaf.com, pero dentro de tu propia instalación local. Las imágenes de TeX Live que usan las compilaciones aisladas contienen los paquetes y fuentes más populares, probados con las plantillas de nuestra galería, lo que garantiza la máxima compatibilidad con los proyectos locales.

Habilitar las compilaciones aisladas te permite configurar entre qué versiones de TeX Live pueden elegir los usuarios en sus proyectos, además de establecer una versión predeterminada de la imagen de TeX Live para los proyectos nuevos.

Si intentas ejecutar Ayakaleaf Pro sin compilaciones aisladas, tu instancia usará de forma predeterminada una versión de TeX Live con el esquema básico para las compilaciones. Esta versión básica es ligera y solo contiene un subconjunto muy limitado de paquetes de LaTeX, lo que muy probablemente provocará errores de paquetes faltantes a tus usuarios, sobre todo si intentan usar plantillas predefinidas.

Como Ayakaleaf Pro se ha diseñado para funcionar sin conexión, no existe una forma automatizada de integrar las plantillas de la galería de overleaf.com en tu instalación local; sin embargo, es posible hacerlo manualmente plantilla por plantilla. Para más información sobre cómo funciona, consulta nuestra guía de transferencia de plantillas desde overleaf.com: #transferring-templates-from-overleaf.com.

Las compilaciones aisladas requieren que el contenedor sharelatex tenga acceso al socket de Docker de la máquina host (mediante un bind mount) para poder gestionar estos contenedores de compilación hermanos.

​

Cómo funciona

Cuando las compilaciones aisladas están habilitadas, el socket de Docker se monta desde la máquina host en el contenedor sharelatex, de modo que el servicio de compilación del contenedor pueda crear nuevos contenedores de Docker en el host. Después, en cada ejecución del compilador en cada proyecto, el servicio de compilación de LaTeX (CLSI) hará lo siguiente:

• Escribir los archivos del proyecto en una ubicación dentro de OVERLEAF_DATA_PATH.
• Usar el socket de Docker montado para crear un nuevo contenedor texlive para la compilación.
• Hacer que el contenedor texlive lea los datos del proyecto desde la ubicación dentro de OVERLEAF_DATA_PATH.
• Compilar el proyecto dentro del contenedor texlive.

​

Habilitar las compilaciones aisladas

​

Para usuarios del Toolkit

Para habilitar las compilaciones aisladas (también conocidas como contenedores hermanos o Sibling containers), establece las siguientes opciones de configuración en overleaf-toolkit/config/overleaf.rc:

config/overleaf.rc

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

Para usuarios de Docker Compose

A partir de Overleaf CE/Server Pro 5.0.3, las variables de entorno cambiaron de nombre de SHARELATEX_* a OVERLEAF_*.

Si usas una versión 4.x (o anterior), asegúrate de que las variables tengan el prefijo correspondiente (p. ej., SHARELATEX_MONGO_URL en lugar de 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"
            #...
        #...

​

Configurar la imagen de TeX Live

Si te encuentras en China continental, puedes sustituir ghcr.io por ghcr.nju.edu.cn para acelerar la descarga. Pero NO uses ghcr.nju.edu.cn directamente en la configuración de entorno del Toolkit. Debes mantener ghcr.io como única opción.

Ayakaleaf Pro usa tres variables de entorno para determinar qué imágenes de TeX Live usar para las compilaciones aisladas:

• TEX_LIVE_DOCKER_IMAGE (obligatoria): la imagen de TeX Live predeterminada que se usa para compilar los proyectos nuevos. Esta imagen debe estar incluida en ALL_TEX_LIVE_DOCKER_IMAGES.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (obligatoria): una lista separada por comas de nombres descriptivos para las imágenes, que se usan en las opciones del frontend.
• ALL_TEX_LIVE_DOCKER_IMAGES (obligatoria): una lista separada por comas de las imágenes de TeX Live que se usarán. Si se usa el Overleaf Toolkit para el despliegue, estas imágenes se descargarán o actualizarán. Para omitir la descarga, establece SIBLING_CONTAINERS_PULL=false en config/overleaf.rc.

Al iniciar tu instancia de Ayakaleaf Pro con el comando bin/up, el Toolkit descargará automáticamente todas las imágenes indicadas en ALL_TEX_LIVE_DOCKER_IMAGES.

Este es un ejemplo en el que usamos TeX Live 2026 de forma predeterminada para los proyectos nuevos y mantenemos 2025 para los proyectos antiguos.

Instalación mínima

La siguiente configuración instala todas las imágenes de Docker completas de TeX Live de 2025 a 2026. Recomendamos disponer de al menos 64 GB de almacenamiento libre antes de usar esta configuración.

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

Instalación completa

La siguiente configuración instala todas las imágenes de Docker completas de TeX Live de 2020 a 2026. Recomendamos disponer de al menos 150 GB de almacenamiento libre antes de usar esta configuración.

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

Se recomienda encarecidamente configurar al menos 2 imágenes texlive-full. Para conocer el motivo en detalle, consulta #known-issues

​

Imágenes de TeX Live disponibles

Esta es una serie de imágenes de TeX Live especialmente optimizadas para Overleaf, que también pueden añadirse a TEX_LIVE_DOCKER_IMAGE y ALL_TEX_LIVE_DOCKER_IMAGES:

• ghcr.io/ayaka-notes/texlive-full:2026.1 (también con la etiqueta 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

Existe un esquema estricto sobre cómo deben etiquetarse las imágenes (se aplica la expresión regular ^[0-9]+.[0-9]+, en la que el primer número determina el año de TeX Live y el segundo la versión del parche).

​

¿Puedo usar otro registro de imágenes?

Algunas personas se preguntan si pueden sustituir ghcr.io por otro sitio espejo, o cambiar texlive por otra imagen de Docker Hub.

No, no lo recomendamos porque la configuración es relativamente complicada. Si descargas desde un sitio espejo, puedes renombrar tu imagen a ghcr.io/ayaka-notes/texlive-full.

Pero, si realmente quieres usar tu propio registro de imágenes, añade:

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

Después, debes asegurarte de que todas las imágenes de texlive estén en your-repo, por ejemplo:

• hub.your.com/your-repo/texlive-full:2025.1
• hub.your.com/your-repo/texlive-full:2024.1

Para más información, lee el siguiente código fuente para entender cómo interpretamos tu variable de entorno:

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
}

​

Sincronización automática de imágenes de TeX Live

Para evitar tener que actualizar manualmente tu instancia con bin/up cada vez, puedes automatizar las actualizaciones de tu imagen de TeX Live. Consulta updating-tex-live-full-images-automatically.md.

​

Problemas conocidos

Este es un caso real de la comunidad de Overleaf:

Usando 6.0.1-ext-v3.3, tengo esta configuración en variables.env:

TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full
ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full

Esto funciona bien con texlive/texlive:latest-full. Sin embargo, descargué otra imagen de texlive, danteev/texlive:2025-10-15, y cambié ambas variables al nombre de la nueva imagen, pero no funciona:

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

En los registros veo lo siguiente:

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

Parece que la configuración actualizada de variables.env no surte efecto. La compilación sigue intentando ejecutar la imagen texlive/texlive:latest-full, no la nueva.

He probado a reiniciar, a eliminar los contenedores y volver a ejecutarlos, pero sigue ocurriendo lo mismo.

¿Alguna solución?

Debido a ciertas limitaciones técnicas, si solo configuras una única imagen de Docker de TeXLive, como 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

y, tras ejecutar tu instancia de Overleaf durante un tiempo, quieres cambiar la imagen de TeXLive a texlive-fullB:latest, verás que tus usuarios no pueden compilar ningún proyecto.

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

Esto se debe a que el nombre de la imagen de TeXLive-Full (para la compilación aislada) de cada proyecto se guarda en la base de datos. El nombre de la imagen solo cambia en la base de datos cuando el usuario cambia la versión de TeXLive de su proyecto, por ejemplo, de 2024 a 2025.

Cuando CLSI compila un proyecto, usa directamente el nombre de la imagen del contenedor que encuentra en la base de datos para compilarlo.

Si solo proporcionas una imagen de Docker, los usuarios no podrán cambiar la imagen usada para compilar el proyecto. En ese caso, tendrás que escribir un script para modificar manualmente la imagen de TeXLive de todos los proyectos de usuario en MongoDB.

​

Depuración y notificación de problemas

Ejecuta el siguiente comando para consultar el registro de clsi desde el Toolkit:

bin/logs clsi

Si encuentras algún problema al compilar con las imágenes de TeX Live, abre una incidencia aquí:

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

Para ayudarnos a reproducir y solucionar el problema, es posible que te pidamos que subas tu proyecto a Overleaf. Después descargaremos el proyecto y ejecutaremos pruebas de compilación con GitHub Action.