\section{لماذا FormaTeX في Docker}
صور أصغر وبناء أنظف
يضيف تضمين TeX Live في صورة Docker غيغابايتات ودقائق إلى عملية البناء. يتولى FormaTeX التجميع عن بُعد، فتبقى حاويتك خفيفة.
وفّر حوالي 4 غيغابايت من حجم الصورة
يتجاوز حجم TeX Live الكامل 4 غيغابايت. مع FormaTeX لا يضيف ملف Dockerfile لديك سوى curl وjq، أي بضعة ميغابايتات فقط.
مخرجات متسقة في كل مكان
يعمل كل بناء على إصدار محرك FormaTeX نفسه. لا مزيد من اختلافات PDF بين بيئة التطوير وCI بحجة «يعمل على جهازي».
لا مشكلات في الأذونات
يتطلب TeX Live صلاحية الكتابة في مجلدات الحزم. ويُنهي التجميع عبر API مشكلات أذونات نظام الملفات في الحاويات دون صلاحيات الجذر.
\section{ملف Dockerfile بسيط}
ملف Dockerfile دون TeX Live
ابدأ من alpine:latest، وثبّت curl وjq، وانسخ سكربت التجميع، وانتهى الأمر. حجم الصورة كلها أقل من 20 ميغابايت.
# 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}
سكربت التجميع
يتحقق سكربت POSIX shell هذا من البيئة، ويقرأ ملف المصدر، ويرسله بطلب POST إلى FormaTeX API عبر jq لترميز JSON بأمان. يمكن ضبط المحرك والمسارات عبر الوسائط ومتغيرات البيئة.
#!/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}
التركيب مع تطبيقك
اربط مجلدًا محليًا كوحدة تخزين (volume) ليقرأ المُجمِّع ملفات .tex الخاصة بك ويكتب ملفات PDF إلى القرص. يُحقن FORMATEX_API_KEY من بيئة المضيف، ولا يُضمَّن أبدًا في الصورة.
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{بناء متعدد المراحل}
ابنِ التطبيق وملفات PDF في خط معالجة (pipeline) واحد
يبني ملف Dockerfile متعدد المراحل هذا تطبيق Node.js، ويجمّع جميع قوالب التقارير .tex عبر FormaTeX، ويكوّن الصورة النهائية مع ملفات PDF المجمّعة مسبقًا داخل public/reports/. مرّر FORMATEX_API_KEY كوسيط بناء، فلا يُضمَّن أبدًا في الطبقة النهائية.
# 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{متغيرات البيئة}
تمرير مفتاح API بأمان
docker run -e
مرّر المفتاح مباشرة وقت التشغيل. تأتي القيمة من بيئة الصدفة لديك وليس من الصورة.
.env file
احتفظ بالمفتاح في ملف .env (لا يُودَع أبدًا في نظام التحكم بالإصدارات) وأشِر إليه بالخيار --env-file.
أسرار Docker
لعمليات النشر في Swarm أو Compose بالإنتاج، استخدم أسرار Docker حتى لا يظهر المفتاح أبدًا كمتغير بيئة عادي.
\section{Troubleshooting}
المشكلات الشائعة وحلولها
jq غير موجود في الصورة
يستخدم السكربت compile.sh الأداة jq لترميز مصدر LaTeX بأمان كـ JSON. في Alpine أضفها بالأمر apk add --no-cache curl jq. وفي Debian/Ubuntu استخدم apt-get install -y curl jq. بدون jq ستُفسد الأحرف الخاصة في ملف .tex حمولة JSON.
مشكلات مسارات الملفات مع وحدات التخزين
عند ربط وحدات التخزين، يجب أن يطابق المسار داخل الحاوية ما يستلمه السكربت. إذا ربطت ./documents بالمسار /app/documents، فاستدعِ السكربت بالصيغة ./compile.sh documents/thesis.tex. استخدم المسارات المطلقة داخل الحاوية لتجنب الالتباس.
تقييد المعدل في عمليات البناء الكبيرة
تتيح الخطة المجانية 15 عملية تجميع عبر API شهريًا. إذا كان البناء متعدد المراحل لديك يجمّع ملفات كثيرة، فأضف انتظارًا قصيرًا بين الطلبات أو قم بالترقية إلى خطة مدفوعة بحدود معدل أعلى. تعيد API الرمز HTTP 429 عند بلوغ الحد.
\section{تكاملات ذات صلة}
استخدم FormaTeX من أي بيئة
استدعاء API نفسه يعمل في أي مشغّل CI أو دالة سحابية أو سكربت محلي.

