How to Self-Host Stirling-PDF with Docker

What Is Stirling-PDF?

Stirling-PDF is a self-hosted web-based PDF manipulation tool. It handles everything you’d use Adobe Acrobat for: merge, split, rotate, compress, convert, add watermarks, OCR, sign, and dozens more operations — all through a clean web UI. No documents leave your server. It replaces Adobe Acrobat, Smallpdf, ILovePDF, and similar online PDF tools.

Updated March 2026: Verified with latest Docker images and configurations.

Stirling-PDF processes everything locally — your documents are never sent to third-party servers.

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
256 MB of free RAM (1 GB recommended for OCR features)
2 GB of free disk space
A domain name (optional, for remote access)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:2.7.3
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      DOCKER_ENABLE_SECURITY: "false"      # Set to "true" to enable login
      LANGS: "en_GB"                       # UI language
      SYSTEM_DEFAULTLOCALE: "en-US"
    volumes:
      - stirling_data:/usr/share/tessdata   # OCR language data
      - stirling_config:/configs            # Custom settings
      - stirling_logs:/logs                 # Application logs
      - stirling_pipeline:/pipeline         # Automated pipelines
      - stirling_custom:/customFiles        # Custom HTML/CSS
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  stirling_data:
  stirling_config:
  stirling_logs:
  stirling_pipeline:
  stirling_custom:

Start the stack:

docker compose up -d

Initial Setup

Open http://your-server-ip:8080 in your browser
Stirling-PDF is ready to use immediately — no account setup required (unless you enabled security)
The home page shows all available PDF operations organized by category

If you enabled DOCKER_ENABLE_SECURITY: "true":

Default credentials: admin / stirling
Change the admin password immediately after first login

Configuration

Authentication

Enable user authentication for multi-user or public-facing deployments:

environment:
  DOCKER_ENABLE_SECURITY: "true"
  SECURITY_ENABLELOGIN: "true"
  SECURITY_INITIALLOGIN_USERNAME: "admin"
  SECURITY_INITIALLOGIN_PASSWORD: "change_this_password"

OCR Languages

Stirling-PDF uses Tesseract for OCR. Additional languages are downloaded on first use, or you can pre-install them:

environment:
  INSTALL_BOOK_AND_ADVANCED_HTML_OPS: "true"    # Enables Calibre-based conversions
  LANGS: "en_GB"

Custom Branding

Customize the application name and UI:

environment:
  APP_NAME: "Our PDF Tools"

Mount custom files to /customFiles for HTML/CSS overrides.

Advanced Configuration (Optional)

Pipeline Automation

Stirling-PDF supports automated pipelines — predefined sequences of PDF operations:

Create pipeline configs in the /pipeline volume
Upload a PDF → select a pipeline → get the processed result

API Usage

Stirling-PDF exposes a REST API at /api/v1/. Every web UI operation is available programmatically:

# Merge two PDFs
curl -X POST "http://localhost:8080/api/v1/general/merge-pdfs" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o merged.pdf

# OCR a PDF
curl -X POST "http://localhost:8080/api/v1/misc/ocr-pdf" \
  -F "[email protected]" \
  -F "languages=eng" \
  -o ocr-output.pdf

Full API docs are available at http://your-server:8080/swagger-ui/index.html.

Reverse Proxy

Nginx Proxy Manager config:

Scheme: http
Forward Hostname: stirling-pdf
Forward Port: 8080

For large file uploads, increase the proxy timeout and max body size. In Nginx:

client_max_body_size 100M;
proxy_read_timeout 300s;

See Reverse Proxy Setup for full configuration.

Backup

Stirling-PDF is mostly stateless — it processes files on-demand. Back up the stirling_config volume if you’ve customized settings, and stirling_pipeline if you’ve created automated pipelines.

docker run --rm -v stirling_config:/data -v $(pwd):/backup alpine \
  tar czf /backup/stirling-config-$(date +%Y%m%d).tar.gz /data

See Backup Strategy for a complete backup approach.

Troubleshooting

OCR Produces Empty or Garbled Text

Symptom: OCR output has no recognizable text or garbage characters. Fix: Ensure the correct language is specified. For scanned documents in non-English languages, select the appropriate Tesseract language in the OCR operation settings.

Large File Uploads Fail

Symptom: Uploading PDFs over 10 MB fails with a timeout or error. Fix: If behind a reverse proxy, increase client_max_body_size and proxy timeout. Stirling-PDF itself has no upload limit — the bottleneck is usually the proxy.

Container Uses High Memory During Conversion

Symptom: Container OOM-killed during complex operations. Fix: LibreOffice-based conversions (DOCX→PDF, etc.) are memory-intensive. Ensure at least 1 GB RAM is available. For OCR on large documents, 2 GB is safer.

Resource Requirements

RAM: ~100 MB idle (30% lower since v2.6.0), 512 MB-1 GB during OCR or conversion operations
CPU: Low idle, medium during active processing
Disk: ~500 MB for the application image (30-40% smaller since v2.6.0), minimal data storage (files are processed and not retained)

Verdict

Stirling-PDF is the best self-hosted PDF tool. It handles everything Adobe Acrobat does without sending your documents to the cloud. The web UI is intuitive, the API makes automation easy, and it’s completely stateless — no database, no complex setup. It doesn’t replace Paperless-ngx for document management and archival — Stirling-PDF is a tool, not an archive. Use both: Paperless-ngx for organizing and searching your documents, Stirling-PDF for manipulating them.

Frequently Asked Questions

Is Stirling-PDF free for commercial use?

Yes. Stirling-PDF is licensed under GPL-3.0 with no usage restrictions. You can run it for personal or commercial use, process unlimited documents, and have unlimited users. There is no paid tier or feature gating.

Does Stirling-PDF store my documents?

No. Stirling-PDF is stateless — it processes files in memory and discards them after the operation completes. No documents are saved on the server unless you explicitly use the pipeline feature. This makes it safe for handling sensitive documents like contracts and financial records.

Can Stirling-PDF do OCR on scanned documents?

Yes. Stirling-PDF includes Tesseract OCR for extracting text from scanned PDFs. It supports 100+ languages — additional language packs download automatically on first use. For best results, ensure the scanned document is at least 300 DPI. Set INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true for Calibre-based conversions alongside OCR.

How does Stirling-PDF compare to Paperless-ngx?

They solve different problems. Stirling-PDF is a PDF manipulation tool — merge, split, convert, OCR. Paperless-ngx is a document management system — it stores, organizes, tags, and searches your documents. Use both together: Paperless-ngx for archiving and searching, Stirling-PDF for editing and converting.

Does Stirling-PDF have an API?

Yes. Every operation available in the web UI is also available through the REST API at /api/v1/. Full API documentation is available at /swagger-ui/index.html on your instance. This makes it easy to integrate PDF operations into automated workflows.

Can I run Stirling-PDF on a Raspberry Pi?

Yes. Stirling-PDF runs on ARM64 hardware including the Raspberry Pi 4 and 5. Basic PDF operations (merge, split, rotate) work well. OCR and document conversion are slower on ARM due to the CPU-intensive nature of those operations — expect longer processing times for large documents compared to an x86 server.