How to Deploy Stirling-PDF Using Docker: Complete Guide to Dockerfile Variants

Deploy Stirling-PDF using Docker by selecting from four optimized image variants—Unified (full features), Unified-lite (minimal dependencies), Ultra-lite (API-only), or Fat (air-gapped)—each defined in specific Dockerfiles under the docker/ directory and built via multi-stage pipelines to match your resource constraints and deployment environment.

Stirling-Tools/Stirling-PDF distributes four distinct Docker images engineered for different operational requirements, from production servers requiring full OCR capabilities to edge devices running headless API workloads. Each variant follows a standardized multi-stage build process—frontend compilation with Node 20, backend packaging with Gradle, and minimal Alpine or Temurin runtime stages—ensuring you deploy only the dependencies necessary for your use case. This guide walks through building, configuring, and running each Dockerfile variant with precise configuration parameters extracted from the source repository.

Understanding the Dockerfile Variants

Stirling-PDF provides four Dockerfiles targeting specific deployment scenarios. Each file resides in a specific path within the repository and produces images with varying sizes and capabilities.

Unified (Full) Image

The Unified variant defined in docker/Dockerfile.unified【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/Dockerfile.unified#L1-L158】 provides the complete feature set including the React frontend, Spring Boot backend, LibreOffice, ImageMagick, Tesseract OCR, OCRmyPDF, and extended font libraries. This image uses alpine:3.22.1 as the base and installs the full tool chain (see the apk add block spanning lines 99-136)【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/Dockerfile.unified#L99-L136】. Deploy this when you require production-grade PDF conversion with OCR and office document support.

Unified-Lite Image

The Unified-lite variant in docker/Dockerfile.unified-lite【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/Dockerfile.unified-lite#L1-L120】 ships the frontend and backend but excludes optional heavy dependencies like Tesseract OCR, Calibre, and extra fonts. This variant suits low-memory environments where only core PDF manipulation (merge, split, rotate) is required. The runtime stage installs only the minimal Java runtime and nginx, significantly reducing the container footprint compared to the full unified build.

Ultra-Lite Image

The Ultra-lite variant located at docker/embedded/Dockerfile.ultra-lite【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/embedded/Dockerfile.ultra-lite#L1-L123】 produces a minimal API-only container approximately 60MB in size. Unlike the unified variants, this Dockerfile bundles the frontend assets directly into the Spring Boot JAR using a Temurin 25-JRE base image (runtime stage starts at line 42)【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/embedded/Dockerfile.ultra-lite#L42-L108】. It installs only openjdk21-jre, nginx, ca-certificates, tini, and bash, making it ideal for headless microservices and CI/CD pipelines that consume the REST API directly.

Fat Image

The Fat variant in docker/embedded/Dockerfile.fat【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/embedded/Dockerfile.fat#L1-L606】 extends the unified image with additional fonts and a complete Calibre build for air-gapped installations. The Dockerfile includes a COPY --link --from=calibre-build section around line 88【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/embedded/Dockerfile.fat#L88-L96】 that embeds the Calibre binaries and font libraries directly into the image. Use this when deploying to environments without internet access where you cannot下载 additional dependencies at runtime.

Building the Docker Images

All variants utilize multi-stage builds. Execute these commands from the repository root to build each image locally:

# Unified (full) - includes OCR, LibreOffice, and all fonts

docker build -f docker/Dockerfile.unified -t stirlingpdf:unified .

# Unified-lite - core PDF operations only

docker build -f docker/Dockerfile.unified-lite -t stirlingpdf:unified-lite .

# Ultra-lite - API-only, minimal footprint

docker build -f docker/embedded/Dockerfile.ultra-lite -t stirlingpdf:ultra-lite .

# Fat - air-gapped with embedded Calibre and fonts

docker build -f docker/embedded/Dockerfile.fat -t stirlingpdf:fat .

The build process compiles the frontend from the frontend/ directory and packages the Spring Boot application from app/core/ into an executable JAR before creating the final runtime image.

Running Stirling-PDF Containers

All images expose port 8080 for the web interface and API. The unified variants additionally support an internal backend port configuration via environment variables.

Standard Deployment (Unified and Unified-Lite)

Deploy the full-featured or minimal unified image using this command structure:

docker run -d \
  -p 8080:8080 \
  -e MODE=BOTH \
  -e PUID=1000 \
  -e PGID=1000 \
  -e STIRLING_TEMPFILES_DIRECTORY=/tmp/stirling-pdf \
  --name stirlingpdf \
  stirlingpdf:unified

Key environment variables (declared in the final stage of each Dockerfile):

• MODE: Configures service exposure. Set to BOTH (default) to serve UI and API, FRONTEND for UI only, or BACKEND for API only. This variable is defined in lines 93-95 of the unified Dockerfile【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/Dockerfile.unified#L93-L95】.
• PUID/PGID: User and group IDs for the non-root user inside the container, ensuring proper file permission mapping to the host.
• JAVA_BASE_OPTS: JVM memory tuning defaults to 75% of container RAM with G1GC. Override with JAVA_CUSTOM_OPTS for specific heap settings (see lines 78-80)【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/Dockerfile.unified#L78-L80】.
• STIRLING_JVM_PROFILE: Select balanced (default) or performance presets for JVM flags, defined in lines 66-68 of the fat Dockerfile【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/embedded/Dockerfile.fat#L65-L68】.

API-Only Deployment (Ultra-Lite)

The ultra-lite variant does not ship the React UI. Run it for headless API consumption:

docker run -d \
  -p 8080:8080 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e STIRLING_TEMPFILES_DIRECTORY=/tmp/stirling-pdf \
  --name stirlingpdf-api \
  stirlingpdf:ultra-lite

All conversion endpoints remain accessible at http://localhost:8080/api/v1/.

Air-Gapped Deployment (Fat)

For environments without internet access, deploy the fat image with embedded dependencies:

docker run -d \
  -p 8080:8080 \
  -e MODE=BOTH \
  -e FAT_DOCKER=true \
  -e INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true \
  --name stirlingpdf-fat \
  stirlingpdf:fat

The FAT_DOCKER=true flag activates the pre-baked Calibre binaries and font libraries, while INSTALL_BOOK_AND_ADVANCED_HTML_OPS ensures the container recognizes the embedded conversion tools. Because all dependencies exist within the image layers, no external network calls are required at runtime.

Verifying Your Deployment

All containers expose a health-check endpoint at /api/v1/info/status. Validate your deployment with:

curl -s http://localhost:8080/api/v1/info/status | jq .

A successful response containing "status":"OK" confirms the JVM started correctly and all native tools (LibreOffice, Tesseract, etc.) are accessible within the container namespace.

Configuration Deep Dive

The container initialization logic resides in docker/unified/entrypoint.sh【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/unified/entrypoint.sh】, which handles user creation, permission fixes, and JVM option construction before launching the Spring Boot application.

For the fat image specifically, the scripts/init-without-ocr.sh script generates a Leyden AOT cache on first startup (lines referenced in the fat build), improving subsequent startup times in air-gapped environments.

Additional runtime variables include:

• QTWEBENGINE_CHROMIUM_FLAGS: Configures headless Chromium for LibreOffice PDF exports.
• UNO_PATH and LIBREOFFICE_BIN_PATH: Point to LibreOffice binaries for the UNO bridge (required for document conversion).

Summary

• Choose docker/Dockerfile.unified for production deployments requiring full OCR, LibreOffice conversion, and web UI capabilities.
• Select docker/Dockerfile.unified-lite when you need core PDF manipulation without OCR or office document support in memory-constrained environments.
• Use docker/embedded/Dockerfile.ultra-lite for headless API-only deployments where container size matters, producing ~60MB images.
• Deploy docker/embedded/Dockerfile.fat for offline/air-gapped networks where the image must contain all fonts and Calibre binaries pre-installed.
• Set MODE=BOTH (default) to expose both UI and API, or restrict to specific modes using the unified variants.
• Verify deployments via the /api/v1/info/status health endpoint to ensure native toolchains initialized correctly.

Frequently Asked Questions

What is the difference between the Unified and Unified-lite Dockerfile variants?

The Unified Dockerfile includes Tesseract OCR, Calibre, LibreOffice, ImageMagick, and extended font packages, while the Unified-lite variant excludes OCR engines and heavy conversion tools to reduce memory and storage overhead. According to the source code in docker/Dockerfile.unified lines 99-136【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/Dockerfile.unified#L99-L136】, the full variant installs approximately 15 additional Alpine packages compared to the lite version.

Can I deploy Stirling-PDF without the web interface?

Yes. Build and run the Ultra-lite variant from docker/embedded/Dockerfile.ultra-lite【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/embedded/Dockerfile.ultra-lite】. This Dockerfile bundles the frontend assets directly into the Spring Boot JAR but does not serve the React UI, exposing only the REST API on port 8080. This configuration is optimal for microservices and automated pipelines consuming PDF conversion endpoints.

How do I deploy Stirling-PDF in an air-gapped environment without internet access?

Use the Fat image built from docker/embedded/Dockerfile.fat【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/embedded/Dockerfile.fat】. This variant embeds Calibre binaries and font libraries during the build phase (see the COPY --link --from=calibre-build instruction around line 88)【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/embedded/Dockerfile.fat#L88-L96】, eliminating runtime dependency downloads. Set FAT_DOCKER=true and INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true when running the container to activate the embedded tools.

What are the minimum system requirements for each Docker variant?

The Ultra-lite variant requires approximately 60MB disk space and 256MB RAM, suitable for Raspberry Pi and edge devices. The Unified-lite variant requires roughly 500MB RAM without OCR workloads. The full Unified and Fat variants require 2GB+ RAM when performing OCR or document conversion, with the JVM configured via JAVA_BASE_OPTS to utilize 75% of available container memory by default (lines 78-80 of the unified Dockerfile)【https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docker/Dockerfile.unified#L78-L80】.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}