How to Self Host Stirling PDF with Docker: Complete Guide

Managing PDF documents securely without relying on third-party cloud services is a common requirement for privacy-conscious organizations and power users. Stirling-PDF is a robust, feature-rich, locally hosted web application that allows you to perform virtually any operation on PDF files—ranging from merging and splitting to OCR, conversion, and compression—entirely on your own infrastructure.

By leveraging Docker, you can deploy Stirling-PDF quickly, maintain strict isolation, and ensure seamless updates. This comprehensive guide walks you through the architecture, prerequisites, step-by-step deployment, and operational best practices needed to successfully run Stirling-PDF in your self-hosted environment.

Understanding Stirling-PDF Architecture

Stirling-PDF is engineered as a monolithic Java-based web application powered by Spring Boot, with heavy lifting provided by robust backend libraries like Apache PDFBox. Unlike lightweight scripts, it packages a comprehensive suite of utilities into a clean, modern web interface. Key capabilities include:

• Document Manipulation: Merge, split, rotate, and rearrange pages effortlessly.
• Conversion Utilities: Convert PDFs to images, Word, Excel, HTML, and vice versa.
• Security Operations: Add passwords, remove permissions, sign digitally, and redact sensitive information.
• Advanced Processing: Apply OCR (Optical Character Recognition) using Tesseract, compress file sizes, and add custom watermarks.

Running this tool via Docker containerization ensures that all heavy dependencies—such as Java runtimes, Python scripts for OCR, and LibreOffice for document rendering—are bundled neatly inside the image, eliminating host-system pollution.

Prerequisites for Deployment

Before launching your container, ensure your host system meets the following minimal requirements:

• A running Docker Engine (version 20.10 or higher).
• Docker Compose installed for declarative multi-container management.
• Sufficient system resources: While idle resource consumption is low, resource-intensive tasks like OCR and large document conversions require at least 2 GB of RAM and multiple CPU cores.

Step-by-Step Deployment Using Docker Compose

Declarative deployment using Docker Compose is the industry standard for managing self-hosted services. It guarantees reproducible configurations and simplifies volume mounting for persistent storage or custom configurations.

1. Create a Project Directory

Open your terminal and establish a dedicated directory for your Stirling-PDF deployment:

mkdir -p ~/stirling-pdf && cd ~/stirling-pdf

2. Write the docker-compose.yml File

Create a docker-compose.yml file using your preferred text editor. Paste the following configuration, which pulls the latest stable image and maps necessary persistent volumes:

version: '3.8'

services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    container_name: stirling-pdf
    ports:
      - "8080:8080"
    volumes:
      - ./configs:/configs
      - ./logs:/logs
      - ./tessdata:/usr/share/tessdata # Optional for OCR language packs
    environment:
      - DOCKER_ENABLE_SECURITY=false
      - INSTALL_BOOK_AND_SPLIT=false
      - LANGS=en_US
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

3. Launch the Container

Run the following command in the directory containing your configuration file to download the image and spin up the container in detached mode:

docker compose up -d

Monitor the startup logs to ensure the Spring Boot application initializes successfully:

docker compose logs -f stirling-pdf

Once initialized, open your web browser and navigate to http://your-server-ip:8080 to access the Stirling-PDF dashboard.

Advanced Configuration and Customization

To tailor Stirling-PDF for production environments, you can modify environment variables and mount custom configurations.

Enabling Authentication

By default, Stirling-PDF runs without forced authentication. If your instance is exposed beyond a trusted local network, enable built-in security by altering the environment variables in your docker-compose.yml file:

    environment:
      - DOCKER_ENABLE_SECURITY=true
      - INITIAL_USERNAME=admin
      - INITIAL_PASSWORD=your_secure_password_here

Resource Limits

Because document rendering and OCR operations can occasionally spike CPU and memory usage, it is a best practice to define resource constraints within your Docker Compose file:

    deploy:
      resources:
      limits:
        cpus: '2.0'
        memory: 4G
      reservations:
        cpus: '0.5'
        memory: 1G

Frequently Asked Questions

How do I update Stirling-PDF to the latest version?

Because the configuration uses the latest tag, updating the application is a straightforward three-step process. Navigate to your project directory and execute:

docker compose pull
docker compose down
docker compose up -d

This pulls the newest upstream image, stops the old container gracefully, and spins up the updated instance without losing configuration data stored in your mapped volumes.

Is my document data sent to external servers?

No. Stirling-PDF is completely self-hosted. All processing happens locally inside your Docker container. Your PDF files never leave your infrastructure, making it fully compliant with strict data privacy regulations like GDPR, HIPAA, and CCPA.

How can I add custom languages for OCR processing?

Stirling-PDF relies on Tesseract for OCR. To support additional languages, download the corresponding .traineddata files from the official Tesseract repository and place them into the host directory mapped to /usr/share/tessdata in your Docker Compose configuration.

Conclusion

Self-hosting Stirling-PDF via Docker empowers you with a lightning-fast, highly secure, and privacy-first document processing toolkit. By keeping your sensitive files off third-party clouds, you retain absolute sovereignty over your data workflows. Ready to streamline your document management? Deploy your instance today and experience frictionless, local PDF processing.

Disclosure: BriteHacks is reader-supported. When you buy through links on our site or deploy infrastructure, we may earn an affiliate commission at no extra cost to you. As an Amazon Associate, we earn from qualifying purchases.