\usepackage{docker}

LaTeX في Docker دون TeX Live

تثبيت TeX Live بحجم 4 غيغابايت؟ ليس في صورة Docker الخاصة بك. استخدم FormaTeX API لتجميع LaTeX إلى PDF من أي حاوية، سواء Alpine أو Debian أو Node أو أي بيئة تعمل عليها مجموعتك التقنية.

\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

مرّر المفتاح مباشرة وقت التشغيل. تأتي القيمة من بيئة الصدفة لديك وليس من الصورة.

docker run -e FORMATEX_API_KEY=$FORMATEX_API_KEY my-latex-image

.env file

احتفظ بالمفتاح في ملف .env (لا يُودَع أبدًا في نظام التحكم بالإصدارات) وأشِر إليه بالخيار --env-file.

docker run --env-file .env my-latex-image

أسرار Docker

لعمليات النشر في Swarm أو Compose بالإنتاج، استخدم أسرار Docker حتى لا يظهر المفتاح أبدًا كمتغير بيئة عادي.

docker secret create formatex_api_key ./key.txt

\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 أو دالة سحابية أو سكربت محلي.

قلّص حجم صورة Docker اليوم

خطة مجانية: 15 عملية تجميع عبر API شهريًا. لا حاجة إلى بطاقة ائتمان.