Configuración con Docker / CI

No es necesario instalar TeX en su propia máquina: una imagen Docker empaqueta todo el entorno de composición tipográfica, por lo que puede convertir .tex en PDF con el mismo procedimiento en cualquier lugar. Esto se combina naturalmente con CI (integración continua) como GitHub Actions: cada pulsación puede construir el PDF automáticamente y guardarlo como un artefacto. Esta página cubre la popular imagen texlive/texlive y cómo hacer que las compilaciones de TeX sean automatizadas y reproducibles en CI.

¿Por qué escribir en un contenedor?

Si una distribución es el “entorno TeX en sí” (ver Distribuciones), una imagen Docker es la caja que envía ese entorno congelado junto con su OS. Dentro de la caja hay una versión específica de TeX Live, los motores, los paquetes y las fuentes, por lo que, ya sea que su host sea Windows o macOS o un servidor CI, abrir la misma caja le brinda el mismo entorno. Su mayor beneficio es evitar la discrepancia "funciona en mi máquina pero falla en la configuración de mi colega o en CI".

Los contenedores y las instalaciones de escritorio no se excluyen mutuamente. Una división común es escribir día a día con su editor y un TeX local (consulte Instalación de escritorio) y entregar solo la compilación final, la colaboración o la publicación a un contenedor o CI. La palabra clave es reproducibilidad: fije la versión con una etiqueta y la reconstrucción medio año después seguirá produciendo el mismo PDF.

La imagen texlive/texlive

Una imagen ampliamente utilizada para TeX Live es texlive/texlive, publicada como una imagen de Isla de TeX en Docker Hub (docker.io/texlive/texlive) y GitLab (registry.gitlab.com/islandoftex/images/texlive). Dentro está TeX Live (la versión estable en 2026 es TeX Live 2026), con motores, paquetes y herramientas como latexmk. Las compilaciones semanales rastrean las actualizaciones de CTAN.

Las etiquetas te permiten elegir un esquema (nivel de tamaño). Hay cinco mapas (minimal, basic, small, medium, full) y latest hasta el más grande, full (todos los paquetes). Puede combinarlos dependiendo de si se incluyen documentación y fuentes: la etiqueta básica no tiene ninguna de las dos, -doc agrega documentos, -src agrega fuentes y -doc-src agrega ambas. Los documentos y las fuentes son voluminosos; CI rara vez los necesita, por lo que un esquema simple o más pequeño funciona más rápido. También hay variantes de -context para usuarios de ConTeXt.

El uso es simple: docker run con el directorio actual montado en el contenedor, luego ejecute latexmk dentro de él. Aquí hay una compilación única de un main.tex local. --rm descarta el contenedor luego, -v "$PWD":/work asigna su ubicación actual a /work y -w /work lo convierte en el directorio de trabajo. El PDF resultante regresa a su carpeta.

docker run --rm -v "$PWD":/work -w /work texlive/texlive latexmk -pdf main.tex

Para un documento japonés, ejecute un motor específico en lugar de latexmk simple, por ejemplo. latexmk -lualatex main.tex para LuaLaTeX, o latexmk main.tex para la ruta upLaTeX + dvipdfmx una vez que proporcione un .latexmkrc. El montaje funciona de la misma manera: tanto la entrada como la salida se encuentran en su directorio local.

Congele el entorno para lograr reproducibilidad. latest pasa a una nueva instantánea de TeX Live cada semana, así que no la deje como la predeterminada para la versión final de un artículo o el material didáctico publicado. Primero elija el año de lanzamiento y el tipo de TeX Live, y use una etiqueta de lanzamiento histórico cuando sea apropiado. Sin embargo, como señala Docker Hub, incluso las imágenes históricas se pueden reconstruir cuando se actualiza la imagen OS subyacente. Si necesita exactamente el mismo contenedor bit por bit más adelante, fije un resumen de imagen así como una etiqueta, o guarde la imagen en buen estado en su propio registro.

Construcciones automatizadas con GitHub Actions

Para un repositorio GitHub, GitHub Actions puede compilar su .tex en cada inserción. La opción popular es xu-cheng/latex-action@v4. Utiliza un contenedor con TeX Live dentro y llama a latexmk de forma predeterminada, por lo que el flujo de trabajo tiene solo unas pocas líneas. A continuación se muestra un ejemplo mínimo que compila main.tex en la raíz del repositorio en cada envío y guarda PDF como un artefacto de compilación.

name: Build LaTeX document
on: [push]

jobs:
  build_latex:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repository
        uses: actions/checkout@v6

      - name: Compile the document
        uses: xu-cheng/latex-action@v4
        with:
          root_file: main.tex

      - name: Upload the PDF
        uses: actions/upload-artifact@v6
        with:
          name: PDF
          path: main.pdf

Al presionar, se inicia un contenedor en el ejecutor de GitHub y latexmk compila el main.tex nombrado en root_file. Los argumentos predeterminados de latexmk son -pdf -file-line-error -halt-on-error -interaction=nonstopmode, una configuración compatible con CI que se detiene ante los errores y se ejecuta hasta el final sin que se le solicite. El PDF terminado se puede descargar como artefacto desde la página de ejecución de Acciones.

Conozca las principales entradas (with:). root_file es el objetivo de compilación (se permiten globos). Cambie de motor con latexmk_use_lualatex: true por LuaLaTeX o latexmk_use_xelatex: true por XeLaTeX (LuaLaTeX es la ruta más fácil para los japoneses). texlive_version selecciona 2020–2026 o latest, por lo que puede fijar por año para mayor reproducibilidad. os es el sistema operativo base; el predeterminado es el liviano alpine, con debian disponible cuando lo necesita. Para paquetes que usan \write18, configure latexmk_shell_escape: true.

Para hacer que las compilaciones sean más rápidas, puedes almacenar en caché elementos que de otro modo se reinstalarían o volverían a descargar en cada ejecución a través de actions/cache. Dicho esto, latex-action ya incluye un TeX Live sustancial, por lo que la mayoría de los proyectos se ejecutan a una velocidad práctica desde el primer momento. Comience con la configuración mínima y optimice sólo cuando la lentitud se convierta en un problema.

GitLab CI adopta el mismo enfoque

GitLab CI sigue la misma idea, solo que nombras la imagen directamente en lugar de usar una acción dedicada. Configure image: del trabajo en texlive/texlive:latest (o una etiqueta fijada por fecha), ejecute latexmk -pdf main.tex en script: y guarde PDF mediante artifacts:. Debido a que se basa en la misma imagen, obtienes el mismo resultado tipográfico que GitHub Actions.

build:
  image: texlive/texlive:latest
  script:
    - latexmk -pdf main.tex
  artifacts:
    paths:
      - main.pdf

La esencia es la misma en cualquier servicio: dentro de una imagen fijada por versión, deje que latexmk impulse una compilación única y recopile el PDF resultante como un artefacto. Ese es el patrón compartido para ejecutar TeX en un contenedor o CI. La mecánica de las compilaciones automatizadas del día a día se explora con más detalle en las páginas "CI" y "Compilaciones automatizadas".

Prepare el manuscrito para CI

Un manuscrito que se comporta bien en CI no depende de la configuración del editor. El archivo raíz, el motor, los comandos auxiliares y la ubicación de salida se registran en el repositorio. Para trabajos japoneses, coloque .latexmkrc al lado de main.tex y elija explícitamente upLaTeX o LuaLaTeX. Si tanto su computadora portátil como CI ejecutan el mismo latexmk main.tex, evitará el error de último minuto de "solo mi máquina lo construye".

# .latexmkrc: upLaTeX + dvipdfmx
$latex = "uplatex -interaction=nonstopmode -halt-on-error %O %S";
$bibtex = "upbibtex %O %B";
$dvipdf = "dvipdfmx %O -o %D %S";
$pdf_mode = 3;

Confirme este .latexmkrc, y Docker y GitHub Actions construirán el PDF bajo las mismas reglas. En lugar de instalar paquetes ad hoc con tlmgr install durante cada ejecución, elija un esquema TeX Live o una etiqueta de imagen fijada que ya contenga lo que necesita el proyecto; las compilaciones son más rápidas y las fallas son más fáciles de rastrear.