Deploy Stirling-PDF on Docker: Self-Host a Private PDF Toolkit for Your HomeLab

The Hidden Privacy Risk of Online PDF Converters

Most of us have done it: you need to merge signed escrow agreements, redact a passport scan, or compress a 60-page tax return, so you drop them into free services like iLovePDF or SmallPDF. It feels harmless in the moment. However, handing unencrypted financial records, client NDAs, or government IDs to third-party cloud servers is an unnecessary gamble.

Free tiers hit you with 15 MB file caps, queue conversions behind artificial speed throttles, and often cache files on remote servers for hours. Your HomeLab can fix that in five minutes. Spinning up a local document engine gives your household full processing power, zero telemetry, and complete ownership of your data.

Understanding Stirling-PDF Architecture

Stirling-PDF packages split, merge, rotate, redact, watermark, and OCR operations into a single self-hosted web suite. Instead of cobbling together individual CLI scripts, you get a clean web UI backed by a battle-tested stack: Spring Boot, Apache PDFBox, LibreOffice, and Tesseract OCR.

Image Flavors: Full vs. Ultra-Lite

Choosing the right container image depends on your hardware and workload:

• Full (Fat) Image: Bundles LibreOffice, OpenCV, and Tesseract language packs. Use this if you need bidirectional conversions (like .docx or .xlsx to PDF) alongside multi-language OCR scans. Expect memory spikes between 2 GB and 3.5 GB under heavy optical recognition passes.
• Ultra-Lite Image: Strips LibreOffice and heavyweight OCR engines. If you only need core page assembly—merging, splitting, rotating, or password-locking files—this flavor idles under 120 MB of RAM and peaks below 300 MB. It runs comfortably on a Raspberry Pi 4 (2 GB) or an entry-level $4/month VPS.

For most x86 mini PCs (like an Intel N100 or an older Lenovo ThinkCentre tiny node), stick to the full image. It gives you the full feature set without needing external microservice sidecars.

Step-by-Step Stirling-PDF Deployment with Docker Compose

Using Docker Compose ensures your deployment is reproducible, version-controlled, and easy to migrate between hosts.

1. Set Up the Project Directory

Create a dedicated directory to store application state, custom Tesseract data, and automated workflows:

mkdir -p ~/homelab/stirling-pdf/{trainingData,extraConfigs,logs,pipeline}
cd ~/homelab/stirling-pdf

2. Create the Docker Compose File

Write out your docker-compose.yml file:

services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./trainingData:/usr/share/tessdata:rw
      - ./extraConfigs:/configs:rw
      - ./logs:/logs:rw
      - ./pipeline:/pipeline:rw
    environment:
      - DOCKER_ENABLE_SECURITY=false
      - INSTALL_BOOK_AND_ADVANCED_HTML_OPS=false
      - LANGS=en_GB,en_US,de_DE,fr_FR
      - SYSTEM_DEFAULTLOCALE=en_US
      - UI_APPNAME=HomeLab PDF Suite
    deploy:
      resources:
        limits:
          memory: 4G

Key configuration points to keep in mind:

• ./trainingData: Mounts custom .traineddata models into Tesseract. Use this if you process non-Latin alphabets or specialized fonts.
• DOCKER_ENABLE_SECURITY: Keeps the dashboard open to your LAN when set to false. Switch this to true if you expose the instance externally or share your home network with guests.
• LANGS: Defines the OCR dictionaries pulled during first initialization. Keep this list trimmed to the languages you actually use to speed up initial container builds.
• memory: 4G: Converting a 300-page scanned document can briefly push RAM usage high. Setting an explicit hard limit keeps Java from choking neighboring Docker workloads.

3. Launch and Verify the Container

Bring the container up in detached mode:

docker compose up -d

Tail the container output to watch the Java runtime and dependencies come online:

docker compose logs -f stirling-pdf

Once you see the Spring Boot banner and the initialization confirmation in your terminal, point your browser to http://<your-server-ip>:8080. The UI categorizes tools clearly across tabs: Merge & Split, Convert, Security, and Page Ops.

4. Production Hardening and User Accounts

If you route traffic through an external reverse proxy like Caddy, Traefik, or Cloudflare Tunnels, locking down access is non-negotiable. Update your Compose environment flags:

    environment:
      - DOCKER_ENABLE_SECURITY=true
      - SECURITY_ENABLELOGIN=true
      - SECURITY_CSRFDISABLED=false

Restart the container. The default administrator credentials are:

• Username: admin
• Password: stirling

Change this password immediately under Account Settings. From there, you can issue role-based accounts or generate API tokens for programmatic CLI scripts.

In our lab, a 4-core virtual machine with 4 GB of assigned RAM routinely crunches 250 MB architectural blueprints and 400-page bank statements without memory leakage or thread locks.

5. Setting Up Watched Folder Pipelines

The ./pipeline mount unlocks automated batch processing. Point a scanner or network folder to a designated watched sub-directory. Stirling-PDF detects new files, automatically deskews crooked pages, runs OCR, applies lossy compression, and drops clean PDF/A archives straight into your NAS storage folder.

Final Thoughts and Next Steps

Replacing SaaS utilities with self-hosted alternatives is an easy win for any home server. Stirling-PDF trades proprietary trackers and subscription fees for an isolated, high-speed document workstation.

For long-term reliability, front the service with an SSL-terminating reverse proxy, set up an automatic renewal hook via Let’s Encrypt, and back up the extraConfigs folder alongside your standard Borg or Restic snapshot routine.