\section{Pourquoi FormaTeX dans Docker}
Des images plus petites, des builds plus propres
Embarquer TeX Live dans une image Docker ajoute des gigaoctets et des minutes à votre build. FormaTeX gère la compilation à distance : votre conteneur reste léger.
Économisez environ 4 Go sur la taille de l'image
TeX Live complet pèse plus de 4 Go. Avec FormaTeX, votre Dockerfile n'ajoute que curl et jq : quelques mégaoctets au total.
Un résultat cohérent partout
Chaque build s'appuie sur la même version du moteur FormaTeX. Fini les différences de PDF « ça marche sur ma machine » entre le développement et la CI.
Aucun problème de permissions
TeX Live exige un accès en écriture aux répertoires de paquets. La compilation via l'API élimine les casse-têtes de permissions du système de fichiers dans les conteneurs sans privilèges root.
\section{Dockerfile minimal}
Un Dockerfile sans TeX Live
Partez de alpine:latest, installez curl et jq, copiez le script de compilation, et c'est terminé. L'image entière fait moins de 20 Mo.
# 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}
Le script de compilation
Ce script shell POSIX valide l'environnement, lit le fichier source et l'envoie par POST à l'API FormaTeX en passant par jq pour un encodage JSON sûr. Le moteur et les chemins sont configurables via des arguments et des variables d'environnement.
#!/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}
Composer avec votre application
Montez un répertoire local comme volume pour que le compilateur lise vos fichiers .tex et réécrive les PDF sur le disque. La variable FORMATEX_API_KEY est injectée depuis l'environnement de l'hôte, jamais intégrée à l'image.
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{Build multi-étapes}
Construire l'application et les PDF dans un seul pipeline
Ce Dockerfile multi-étapes construit une application Node.js, compile tous les modèles de rapports .tex via FormaTeX et assemble l'image finale avec les PDF précompilés déjà présents dans public/reports/. Passez FORMATEX_API_KEY comme argument de build : elle n'est jamais intégrée à la couche finale.
# 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 d'environnement}
Transmettre la clé API en toute sécurité
docker run -e
Transmettez la clé en ligne à l'exécution. La valeur provient de l'environnement de votre shell, pas de l'image.
.env file
Stockez la clé dans un fichier .env (jamais validé dans le contrôle de version) et référencez-le avec --env-file.
Secrets Docker
Pour les déploiements Swarm ou Compose en production, utilisez les secrets Docker afin que la clé ne soit jamais exposée comme simple variable d'environnement.
\section{Troubleshooting}
Problèmes courants et solutions
jq introuvable dans l'image
Le script compile.sh utilise jq pour encoder en toute sécurité le source LaTeX en JSON. Sur Alpine, ajoutez-le avec apk add --no-cache curl jq. Sur Debian/Ubuntu, utilisez apt-get install -y curl jq. Sans jq, les caractères spéciaux de votre fichier .tex casseront la charge JSON.
Problèmes de chemins avec les volumes
Lorsque vous montez des volumes, le chemin dans le conteneur doit correspondre à ce que reçoit le script. Si vous montez ./documents sur /app/documents, appelez le script avec ./compile.sh documents/thesis.tex. Utilisez des chemins absolus dans le conteneur pour éviter toute ambiguïté.
Limitation de débit sur les builds en masse
L'offre gratuite autorise 15 compilations API par mois. Si votre build multi-étapes compile de nombreux fichiers, ajoutez une courte pause entre les requêtes ou passez à une offre payante avec des limites de débit plus élevées. L'API renvoie HTTP 429 lorsque la limite est atteinte.
\section{Intégrations associées}
Utilisez FormaTeX depuis n'importe quel environnement
Le même appel d'API fonctionne dans n'importe quel runner CI, fonction cloud ou script local.