Stirling-PDF Tutorial: Self-Hosted PDF Docker Guide

Have you ever stopped to think about what happens to your private documents when you upload them to “free” online PDF editors? Whether it is a tax return, a housing lease, a medical record, or a signed legal contract, uploading these files to third-party servers exposes your most sensitive personal information to data harvesting, administrative audits, and potential data breaches.

For years, users had to choose between risking their privacy with online services or paying expensive licensing fees for heavy desktop programs like Adobe Acrobat Pro.

Stirling-PDF changes the equation. It is a robust, feature-rich, and completely open-source web application that allows you to perform over 60 different operations on PDF files—including merging, splitting, converting, OCR scanning, and redacting. Because it runs as a local Docker container on your own hardware, your files never leave your server.

In this guide, we will explore the architecture of Stirling-PDF, walk through a complete Docker Compose installation, configure advanced multi-user security settings, integrate OCR languages, and set up a reverse proxy for secure HTTPS access.

1. Why Stirling-PDF is the FOSS Gold Standard

Stirling-PDF has quickly become one of the most popular self-hosted applications for home servers and enterprise environments alike.

Online PDF Editors (High Risk):
[ Your Document ] ──► ( Internet Upload ) ──► [ Third-Party Server ] ──► ( Storage / Risk )

Stirling-PDF Model (100% Private):
[ Your Document ] ──► [ Your Local Server (Docker) ] ──► [ Done: Instantly Wiped from RAM ]

Key Security and Functional Features:

• 100% Offline Processing: All file operations occur locally inside your container. Stirling-PDF does not call home or upload telemetry to external servers.
• Immediate Cache Wiping: Files are processed in system memory or temporary directories and are immediately deleted once the operation is complete.
• Comprehensive Suite (60+ Tools): Includes split/merge, page rotation, image extraction, password protection, watermarking, compression, and metadata editing.
• Next-Gen Optical Character Recognition (OCR): Powered by the open-source Tesseract OCR engine, allowing you to turn scanned flat images into fully searchable, selectable PDF documents.
• Aesthetic and Responsive UI: Designed with a clean web interface that works on both desktop and mobile web browsers.
• REST API Integration: Exposes API endpoints, allowing developers to automate PDF processing inside custom scripts or workflow platforms (like n8n or Node-RED).

2. Under the Hood: Stirling-PDF Architecture

Stirling-PDF is built on a modular, containerized architecture that leverages several open-source libraries:

• Java Spring Boot: Serves as the primary application framework and API router.
• Apache PDFBox & OpenPDF: Java-based libraries that handle core PDF operations like merging, splitting, and encrypting.
• Tesseract OCR: The underlying engine used to identify characters in scanned documents.
• LibreOffice: Bundled inside the container to handle conversions between PDF and Microsoft Office formats (.docx, .xlsx, .pptx).
• Ghostscript & WeasyPrint: Tools used for advanced rendering, compressing, and HTML-to-PDF generation.

System Resource Footprint

Because Stirling-PDF runs a Java Virtual Machine (JVM) and bundles heavy tools like LibreOffice, it has a larger memory footprint than lightweight Rust or Go tools.

• Idle Memory: Typically consumes between 400MB and 600MB of RAM.
• Under Load: During heavy operations—such as OCR-scanning a 200-page document or converting a complex spreadsheet—memory usage can spike to 1GB or 2GB. Ensure your host system has sufficient memory allocation.

3. Step-by-Step Installation using Docker Compose

The most reliable way to install and manage Stirling-PDF is by using Docker Compose. This ensures your configurations, OCR training data, and user directories remain persistent.

Step 1: Create a Project Directory

Log into your server via terminal and create a dedicated project directory:

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

Step 2: Write the Docker Compose Configuration

Create and edit the deployment configuration file:

nano docker-compose.yml

Paste the following configuration:

version: '3.8'

services:
  stirling-pdf:
    image: frooodle/s-pdf:latest
    container_name: stirling-pdf
    ports:
      - "8080:8080"
    volumes:
      - ./trainingData:/usr/share/tesseract-ocr/4.00/tessdata
      - ./extraConfigs:/configs
      - ./customFiles:/customFiles/
    environment:
      - DOCKER_ENABLE_SECURITY=true
      - SECURITY_INIT_ADMIN_USERNAME=admin
      - SECURITY_INIT_ADMIN_PASSWORD=change_this_secure_password
      - INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true
      - SYSTEM_DEFAULT_LOCALE=en-US
      - UI_THEME=dark
    restart: unless-stopped

Step 3: Deconstructing the Environment Variables

• DOCKER_ENABLE_SECURITY=true: Enforces user authentication. By default, Stirling-PDF has no login screen. Activating this variable enables user accounts, passwords, and API keys.
• SECURITY_INIT_ADMIN_USERNAME & SECURITY_INIT_ADMIN_PASSWORD: Defines the initial credentials for the administrator account. Make sure to change these to secure values before starting the container.
• INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true: Instructs the container to install additional ebook utilities (like Calibre) and HTML converters. This is required if you want to convert files to .epub or .mobi.
• volumes: Maps directories to store custom assets, system configurations, and additional OCR language training data.

4. Step 4: Starting the Application and Creating Users

Start the Stirling-PDF container in the background:

docker compose up -d

The first boot may take several minutes as the container downloads the base images and initializes the Java environment.

Verifying the Startup Logs

Ensure there are no startup errors:

docker compose logs -f

Once you see logs indicating the Spring Boot application has started, open your web browser and navigate to:

http://YOUR_SERVER_IP:8080

(Log in using the SECURITY_INIT_ADMIN_USERNAME and SECURITY_INIT_ADMIN_PASSWORD you defined in your Compose file).

Managing Users and Security Roles

Once logged in as an administrator:

1. Navigate to the Admin Settings page in the top right menu.
2. Change your default admin password immediately.
3. You can create standard user accounts for friends or family members, giving them access to the PDF tools without granting them administrative permissions.
4. You can also generate API Keys to run programmatic PDF operations from external scripts or home automation tools.

5. Integrating Multi-Language OCR (Tesseract)

By default, Stirling-PDF only includes English OCR capabilities. If you need to convert scanned documents written in other languages, you must add Tesseract language pack training files.

Tesseract OCR Pipeline:
[ Scanned PDF / Image ] ──► [ Read OCR Request ] ──► [ Match with ./trainingData/*.traineddata ]
                                                                       │
             [ Selectable Searchable PDF ] ◄───────────────────────────┘

Adding New Languages:

1. Navigate to the official Tesseract OCR Language Repository.
2. Find and download the .traineddata file for your required language (e.g., spa.traineddata for Spanish, fra.traineddata for French, deu.traineddata for German).
3. Place the downloaded file into the ./trainingData folder inside your project directory (~/stirling-pdf/trainingData).
4. Restart your Stirling-PDF container:

   docker compose restart

5. When you open the OCR tool in the web interface, the new language will be selectable in the settings dropdown menu.

6. Configuring a Reverse Proxy (SSL/TLS Setup)

Because Stirling-PDF deals with sensitive files and user credentials, securing the traffic with HTTPS is critical. Here is how to configure a reverse proxy using Caddy or Nginx.

Option A: Caddy (Recommended)

Caddy automatically handles Let’s Encrypt certificates. Add the following to your Caddyfile:

pdf.yourdomain.com {
    reverse_proxy 127.0.0.1:8080 {
        # Increase body limit size for uploading large PDF files
        request_body_limit 100MB
    }
}

Option B: Nginx Virtual Host

For standard Nginx setups, use this configuration:

server {
    listen 80;
    server_name pdf.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name pdf.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/pdf.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pdf.yourdomain.com/privkey.pem;

    # Increase maximum upload file size (essential for large PDFs)
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Disable buffering to avoid memory spikes on large uploads
        proxy_request_buffering off;
        proxy_buffering off;
    }
}

7. The Security Nuance of Proper Text Redaction

A common mistake when handling sensitive documents is drawing a black box over text using a standard editor. This does not delete the text; it simply covers it with a graphic layer. Attackers can copy the covered text and paste it into a text editor, or extract the metadata to read the sensitive information.

Insecure Redaction (Drawing a black box):
[ Sensitive Text ] + [ Overlay Black Box Graphic ] ──► ( Copy-paste still extracts text! )

True Redaction (Stirling-PDF):
[ Sensitive Text ] ──► [ Burn Text / Remove Vector Paths ] ──► [ Render Black Pixels ]

Stirling-PDF’s Auto-Redaction and Manual Redaction tools strip the text vector paths from the underlying file. The text is burned out of the PDF structure and replaced with flat black pixels, ensuring the information can never be extracted.

8. Troubleshooting & Performance Optimization

Issue 1: Out of Memory Crashes during OCR

• Symptom: The container crashes or restarts when processing large documents.
• Cause: The JVM ran out of allocated memory.
• Resolution: Add resource limits to your docker-compose.yml file to allocate sufficient swap space, or increase your server’s RAM:

  deploy:
    resources:
      limits:
        memory: 2G

Issue 2: Office Document Conversions Fail

• Symptom: Converting .docx or .xlsx files to PDF fails with processing errors.
• Cause: LibreOffice is missing or disabled.
• Resolution: Ensure that your container is running the full image (do not use minimal tags) and check that you haven’t disabled converters in the configuration.

Issue 3: “Client Max Body Size” Error on Uploads

• Symptom: Uploading large PDFs returns a 413 Payload Too Large error.
• Cause: Your reverse proxy (Nginx or Caddy) has a default upload file size limit (often 1MB or 2MB).
• Resolution: Add the client_max_body_size 100M; directive to your Nginx configuration, or configure the body limit parameters in your Caddyfile as shown in Step 6.

Conclusion & Setup Checklist

Self-hosting Stirling-PDF provides a secure, private, and powerful alternative to commercial online PDF utilities. By running the service locally in a Docker container, you ensure that your files remain private and secure.

Your Setup Checklist:

• Created a secure administrator username and password.
• Enabled authentication (DOCKER_ENABLE_SECURITY=true).
• Configured a reverse proxy with a valid SSL certificate.
• Configured the proxy to accept large file uploads (e.g., up to 100MB).
• Added Tesseract OCR language files for multi-language support.
• Tested redacting text to verify the vector paths are completely stripped.

Frequently Asked Questions (FAQs)

Q: Are my uploaded files saved on the server permanently?
A: No. Stirling-PDF processes files in temporary directories and deletes them immediately once the operation is complete or when the download is triggered. You can adjust the file cache duration settings in the admin panel.

Q: Can I use Stirling-PDF on my mobile phone?
A: Yes. The web interface is responsive and works well on mobile web browsers, allowing you to scan and sign documents on the go.

Q: Can I customize the look of the web interface?
A: Yes. Stirling-PDF allows you to change the site logo, application title, and theme directly from the settings page or by placing custom CSS files in the ./extraConfigs volume mapping.

Q: How do I update Stirling-PDF to the latest version?
A: To update your container, run these commands in your project directory:

docker compose pull
docker compose down
docker compose up -d

Q: Does Stirling-PDF support digital signatures?
A: Yes. You can sign documents by drawing a signature on your screen, uploading a signature image, or applying digital certificates.

Next Steps for Hardening Your Infrastructure:
Learn how to Configure a UFW Firewall on Linux or explore our Self-Hosted Vaultwarden Setup Tutorial.