Docker Image Variants#

Overview#

Stirling-PDF ships three Docker image variants — latest, latest-fat, and latest-ultra-lite — published to Docker Hub under stirlingtools/stirling-pdf and mirrored to GHCR as ghcr.io/stirling-tools/stirling-pdf 1. Each variant embeds a different set of external binaries, and the application dynamically enables or disables API endpoints at startup based on which tools are actually present in the running container. The same Java codebase powers all variants; the available feature set is determined by the image you pull.

The three embedded-frontend variants are built via the CI/CD pipeline from docker/embedded/Dockerfile, docker/embedded/Dockerfile.fat, and docker/embedded/Dockerfile.ultra-lite. A separate split frontend/backend architecture also exists under docker/backend/ and docker/frontend/, but the public image tags correspond to the embedded variants 2.

Image Variant Comparison#

Ultra-Lite (latest-ultra-lite)#

Built from docker/embedded/Dockerfile.ultra-lite with a direct eclipse-temurin:25-jre-noble base — it does not layer on the shared base image 3. Only minimal OS packages are installed: ca-certificates, tzdata, tini, bash, curl, procps, and util-linux. There is no LibreOffice, Tesseract, Calibre, Ghostscript, ImageMagick, or Python venv.

The JAR is built with DISABLE_ADDITIONAL_FEATURES=true, and ENDPOINTS_GROUPS_TO_REMOVE=CLI is set as a default environment variable to remove all CLI-tool-dependent endpoints at startup 3. The compose stack caps memory at 2 GB 4.

Best for: Raspberry Pi, low-end VPS, environments that only need core PDF manipulation (merge, split, rotate, add/remove pages, watermarks, passwords, metadata, etc.).

Standard (latest)#

Built from docker/embedded/Dockerfile, which layers the application JAR on top of the shared base image stirlingtools/stirling-pdf-base. The base image (docker/base/Dockerfile) builds and installs 5:

• Calibre (ebook-convert) — ebook-to-PDF conversion
• Ghostscript — built from source (~v10.x) for PDF/PS processing
• QPDF — built from source for PDF manipulation
• ImageMagick 7 — built from source with PDF/PS/EPS policy enabled
• LibreOffice (Fresh PPA, nogui packages) with unoserver for document conversion via UNO
• Tesseract OCR with language packs (eng, deu, fra, por, chi-sim, osd)
• Python venv at /opt/venv containing: weasyprint, pdf2image, opencv-python-headless, ocrmypdf, unoserver, cryptography
• System fonts: Noto (core/mono/extra/CJK), DejaVu, Liberation2, Carlito, Caladea, FreeFonts, Terminus

The compose stack caps memory at 4 GB. Best for: most deployments; all PDF features available out of the box.

Fat (latest-fat)#

Built from docker/embedded/Dockerfile.fat, which also uses the same stirling-pdf-base base image as latest. The key differences from the standard image are 6:

• Sets FAT_DOCKER=true as an environment variable. This flag causes the startup script to skip calling download-security-jar.sh, because the security JAR is pre-bundled in the image rather than downloaded at container start 7.
• Includes extra fonts for air-gapped environments — designed for deployments where the container has no outbound internet access at startup.
• The compose stack caps memory at 6 GB 8.

Best for: highest-quality conversions, full format support, environments with no outbound internet access on container start, and when disk space is not a concern.

Summary Table#

9 1

Dynamic Endpoint Enable/Disable Mechanism#

Startup: Binary Detection in Shell Scripts#

The container entrypoint chain is tini → /scripts/init.sh → /scripts/init-without-ocr.sh. The init script uses a command_exists() helper to probe PATH for binaries at runtime. For example, unoserver is only launched if both unoserver and unoconvert are found in PATH 7. init.sh conditionally configures PYTHONPATH and LD_LIBRARY_PATH only when the relevant virtual environments (/opt/venv, /opt/unoserver-venv) exist 10. This means the ultra-lite image starts cleanly with no errors about missing binaries — they are simply absent, not probed.

The print_versions() function in init-without-ocr.sh logs the versions of all detected tools at startup — qpdf, magick, ocrmypdf, soffice, unoserver, tesseract, gs, pdfinfo, fontforge, unpaper, ebook-convert — giving operators a quick way to confirm what is active in a running container 7.

Runtime: Endpoint Availability API#

The Java application exposes GET /api/v1/config/endpoints-availability, which returns a map of endpoint names to their enabled/disabled state. The frontend queries this endpoint on load to determine which tools to display. Calling the endpoint with no query parameters returns all endpoints at once.

Manual Endpoint Group Removal#

Operators can forcibly disable groups of endpoints regardless of whether the underlying binary is installed. This is configured via:

• Environment variable: ENDPOINTS_GROUPS_TO_REMOVE=LibreOffice,Weasyprint,Calibre
• settings.yml:
  ⧉

  endpoints:
    groupsToRemove:
      - LibreOffice
      - Weasyprint
  

The ultra-lite image defaults to ENDPOINTS_GROUPS_TO_REMOVE=CLI, removing all endpoints that invoke external CLI tools 3 4. Known removable groups include LibreOffice, Weasyprint, Calibre, CLI, and FFmpeg (FFmpeg is currently disabled in the codebase due to CVEs) 7.

Feature Flag: DISABLE_ADDITIONAL_FEATURES#

The ultra-lite JAR is compiled with DISABLE_ADDITIONAL_FEATURES=true, which removes additional feature sets at build time. The standard and fat images are compiled with DISABLE_ADDITIONAL_FEATURES=false 3 11.

Key Files and References#

Endpoint availability API: GET /api/v1/info/status (health check), GET /api/v1/config/endpoints-availability (feature availability map).

Memory/performance env vars relevant across variants: STIRLING_JVM_PROFILE (balanced or performance), STIRLING_AOT_ENABLE (AOT cache, off by default), PUID/PGID (user remapping).