\section{Por qué FormaTeX en Docker}
Imágenes más pequeñas, compilaciones más limpias
Incluir TeX Live en una imagen de Docker añade gigabytes y minutos a su compilación. FormaTeX gestiona la compilación de forma remota y su contenedor se mantiene ligero.
Ahorre unos 4 GB de tamaño de imagen
TeX Live completo pesa más de 4 GB. Con FormaTeX, su Dockerfile solo añade curl y jq: unos pocos megabytes en total.
Resultados consistentes en todas partes
Cada compilación se ejecuta con la misma versión del motor de FormaTeX. Se acabaron las diferencias en los PDF del tipo «en mi equipo funciona» entre desarrollo y CI.
Sin problemas de permisos
TeX Live requiere acceso de escritura a los directorios de paquetes. La compilación basada en API elimina los problemas de permisos del sistema de archivos en contenedores sin root.
\section{Dockerfile mínimo}
Un Dockerfile sin TeX Live
Parta de alpine:latest, instale curl y jq, copie el script de compilación y listo. La imagen completa ocupa menos de 20 MB.
# No TeX Live needed — just curl and the FormaTeX API
FROM alpine:latest
RUN apk add --no-cache curl jq
WORKDIR /app
COPY compile.sh .
RUN chmod +x compile.sh
CMD ["./compile.sh"]\section{compile.sh}
El script de compilación
Este script de shell POSIX valida el entorno, lee el archivo fuente y lo envía con POST a la API de FormaTeX mediante jq para una codificación JSON segura. El motor y las rutas se pueden configurar con argumentos y variables de entorno.
#!/bin/sh
# compile.sh — compile main.tex to output.pdf via FormaTeX API
set -e
if [ -z "$FORMATEX_API_KEY" ]; then
echo "Error: FORMATEX_API_KEY environment variable not set"
exit 1
fi
TEX_FILE="${1:-main.tex}"
OUTPUT="${2:-output.pdf}"
ENGINE="${ENGINE:-pdflatex}"
echo "Compiling $TEX_FILE with $ENGINE..."
curl -X POST https://api.formatex.io/api/v1/compile \
-H "X-API-Key: $FORMATEX_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --rawfile src "$TEX_FILE" \
--arg engine "$ENGINE" \
'{"latex": $src, "engine": $engine}')" \
--output "$OUTPUT"
echo "PDF saved to $OUTPUT"\section{docker-compose}
Composición con su aplicación
Monte un directorio local como volumen para que el compilador lea sus archivos .tex y vuelva a escribir los PDF en disco. La variable FORMATEX_API_KEY se inyecta desde el entorno del host y nunca se incluye en la imagen.
version: '3.8'
services:
latex-compiler:
build: .
environment:
- FORMATEX_API_KEY=${FORMATEX_API_KEY}
- ENGINE=pdflatex
volumes:
- ./documents:/app/documents
command: ["./compile.sh", "documents/thesis.tex", "documents/thesis.pdf"]
# Or as part of a larger application
app:
image: your-app:latest
environment:
- FORMATEX_API_KEY=${FORMATEX_API_KEY}
depends_on:
- latex-compiler\section{Compilación en varias etapas}
Genere la aplicación y los PDF en un solo pipeline
Este Dockerfile de varias etapas compila una aplicación Node.js, compila con FormaTeX todas las plantillas de informes .tex y ensambla la imagen final con los PDF ya compilados en public/reports/. Pase FORMATEX_API_KEY como argumento de compilación: nunca se incluye en la capa final.
# Multi-stage: build your app and compile LaTeX in one pipeline
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json .
RUN npm install
COPY . .
RUN npm run build
FROM alpine:latest AS pdf-compiler
RUN apk add --no-cache curl jq
WORKDIR /pdfs
COPY --from=builder /app/reports ./reports
ARG FORMATEX_API_KEY
RUN for tex_file in reports/*.tex; do \
base=$(basename "$tex_file" .tex); \
curl -X POST https://api.formatex.io/api/v1/compile \
-H "X-API-Key: $FORMATEX_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --rawfile src "$tex_file" '{"latex": $src, "engine": "pdflatex"}')" \
--output "reports/$base.pdf"; \
done
FROM node:20-alpine AS runner
COPY --from=builder /app/.next ./.next
COPY --from=pdf-compiler /pdfs/reports ./public/reports\section{Variables de entorno}
Cómo pasar la clave de API de forma segura
docker run -e
Pase la clave en línea en tiempo de ejecución. El valor proviene de su entorno de shell, no de la imagen.
.env file
Guarde la clave en un archivo .env (nunca lo suba al control de versiones) y haga referencia a él con --env-file.
Docker secrets
En despliegues de producción con Swarm o Compose, use Docker secrets para que la clave nunca quede expuesta como variable de entorno sin protección.
\section{Troubleshooting}
Problemas comunes y soluciones
jq no se encuentra en la imagen
El script compile.sh usa jq para codificar de forma segura el código LaTeX como JSON. En Alpine, añádalo con apk add --no-cache curl jq. En Debian/Ubuntu, use apt-get install -y curl jq. Sin jq, los caracteres especiales de su archivo .tex romperán la carga JSON.
Problemas con las rutas de archivo en los volúmenes
Al montar volúmenes, la ruta dentro del contenedor debe coincidir con la que recibe el script. Si monta ./documents en /app/documents, llame al script como ./compile.sh documents/thesis.tex. Use rutas absolutas dentro del contenedor para evitar ambigüedades.
Límite de tasa en compilaciones masivas
El plan gratuito permite 15 compilaciones de API al mes. Si su compilación en varias etapas procesa muchos archivos, añada una breve pausa entre solicitudes o pase a un plan de pago con límites de tasa más altos. La API devuelve HTTP 429 cuando se alcanza el límite.
\section{Integraciones relacionadas}
Use FormaTeX desde cualquier entorno
La misma llamada a la API funciona en cualquier runner de CI, función en la nube o script local.