rbehzadan/tex2pdf repository overview

⁠LaTeX to PDF Conversion Service

A high-performance, secure REST API for converting LaTeX documents to PDF format.

⁠Features

• Simple API: Upload a ZIP file containing LaTeX documents and get a PDF back
• Secure Processing: Comprehensive security measures including input validation and sanitization
• Multiple Workers: Designed for concurrency with shared file system and SQLite database
• Flexible ZIP Layout: Supports main.tex either at the root or inside a single top-level folder (e.g., GitHub or Overleaf exports)
• Robust Error Handling: Detailed error messages with LaTeX compilation logs
• Automatic Cleanup: Background process removes expired PDFs and temporary files
• Configurable Options: custom main file name
• API Key Authentication: Optional security layer with configurable API keys
• Rate Limiting: Protection against API abuse
• Resource Control: Limits on file sizes and compilation time
• Docker Ready: Ready-to-use Docker and Docker Compose configurations

⁠Quick Start

The easiest way to run the service is with Docker Compose:

# Clone the repository
git clone https://github.com/rbehzadan/tex2pdf-docker.git
cd tex2pdf

# Start the service
docker-compose up -d

The service will be available at http://localhost:8000.

⁠API Usage

⁠Convert LaTeX to PDF

curl -X POST \
  -H "X-API-Key: 1234" \
  -F "zip_file=@my_latex_files.zip" \
  http://localhost:8000/tex2pdf

Response:

{
  "job_id": "28f5bf9b-587f-4f3c-a3de-4d737d9736ce",
  "status": "processing",
  "message": "Conversion job started"
}

⁠Check Job Status

curl -X GET \
  -H "X-API-Key: 1234" \
  http://localhost:8000/tex2pdf/status/28f5bf9b-587f-4f3c-a3de-4d737d9736ce

Response:

{
  "job_id": "28f5bf9b-587f-4f3c-a3de-4d737d9736ce",
  "status": "completed",
  "created_at": 1741424390.6039968
}

⁠Download PDF

curl -X GET \
  -H "X-API-Key: 1234" \
  -o output.pdf \
  http://localhost:8000/tex2pdf/download/28f5bf9b-587f-4f3c-a3de-4d737d9736ce

⁠Health Check

curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "database": "connected",
  "storage": true
}

⁠Advanced Usage

⁠Compilation Options

You can specify the main LaTeX file if it's not named main.tex:

curl -X POST \
  -H "X-API-Key: 1234" \
  -F "zip_file=@my_latex_files.zip" \
  -F "options={\"main_file\": \"document.tex\"}" \
  http://localhost:8000/tex2pdf

Options:

• main_file: Main LaTeX file to compile (default: main.tex)

ℹ️ The service now uses latexmk for automatic multiple runs and bibliography support, so you no longer need to set num_runs or use_bibtex.

⁠ZIP File Requirements

• The ZIP file must contain all necessary files for LaTeX compilation
• The service looks for main.tex (or your specified main_file) either:
  • At the root of the ZIP file, or
  • Inside a single top-level folder (e.g., myproject/main.tex)
• All referenced files (images, styles, etc.) should be included
• Paths in LaTeX files should be relative and match the ZIP structure

⁠Configuration

The service can be configured via environment variables in the docker-compose.yml file:

⁠Architecture

The service uses a stateless design with background processing:

1. FastAPI Application: Handles HTTP requests and responses
2. SQLite Database: Stores job metadata and status
3. File System: Stores generated PDFs and temporary files
4. Background Tasks: Process LaTeX compilation asynchronously

⁠Source Code

GitHub Repository: rbehzadan/tex2pdf-docker⁠

⁠License

MIT License⁠