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

> Deploy Stirling-PDF using Docker with four optimized image variants Unified Unified-lite Ultra-lite or Fat. Choose the best Dockerfile for your needs and resource constraints.

- Repository: [Stirling Tools/Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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:

```bash

# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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)【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`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/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】.