How to Self-Host Stirling PDF: 60+ PDF Tools Running on Your Own Server

What Is Stirling PDF?

Stirling PDF is a self-hosted web application for PDF manipulation. It is the most starred PDF tool on GitHub, with over 25 million downloads, and covers every common PDF operation through a clean browser-based interface. You run it as a Docker container on your own server or home machine, and access it from any browser — no installation required on client devices.

What makes it different from online PDF tools is the privacy model. Every operation runs locally on your server. Files are processed in memory and deleted immediately after the operation completes. Nothing is stored, logged, or transmitted to external services.

Why Self-Host Instead of Using Online PDF Tools?

Choosing the Right Docker Image

Stirling PDF offers three Docker image variants. The right choice depends on your hardware and which tools you need:

Setting Up Stirling PDF with Docker Compose

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

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./stirling-data/tessdata:/usr/share/tessdata   # OCR language files
      - ./stirling-data/configs:/configs               # Settings and database
      - ./stirling-data/logs:/logs                     # Application logs
      - ./stirling-data/pipeline:/pipeline             # Automation pipeline configs
      - ./stirling-data/customFiles:/customFiles       # Custom branding
    environment:
      - TZ=Europe/Istanbul
      - SECURITY_ENABLELOGIN=false        # No login required — everyone on network can use it
      - LANGS=en_GB                       # UI language
      - SYSTEM_DEFAULTLOCALE=en-US        # Default locale for number formatting
      - SYSTEM_GOOGLEVISIBILITY=false     # Prevent search engines from indexing
      - SYSTEM_MAXFILESIZE=2000           # Max upload size in MB (default 2000)
      - DISABLE_ADDITIONAL_FEATURES=false # Keep all tools enabled
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/api/v1/info/status || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

docker compose up -d

# Watch the startup log — first start takes longer as it initializes
docker logs -f stirling-pdf

Starting Stirling-PDF v2.9.0
Initializing Tesseract OCR...
Checking LibreOffice availability...
Application started on port 8080

Enabling Login and Authentication

By default, Stirling PDF runs without authentication. Anyone who can reach port 8080 can use all tools. This is fine on a private home network, but before exposing it via a public URL, you should enable login:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./stirling-data/tessdata:/usr/share/tessdata
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/pipeline:/pipeline
    environment:
      - TZ=Europe/Istanbul
      - SECURITY_ENABLELOGIN=true                         # Require login
      - SECURITY_INITIALLOGIN_USERNAME=admin              # Initial admin username
      - SECURITY_INITIALLOGIN_PASSWORD=YourStrongPassword # Initial admin password
      - DISABLE_ADDITIONAL_FEATURES=false
      - LANGS=en_GB
      - SYSTEM_DEFAULTLOCALE=en-US
      - SYSTEM_GOOGLEVISIBILITY=false
      - SYSTEM_MAXFILESIZE=2000

After enabling login, additional users can be created from Settings → User Management in the admin account. Each user can be assigned different permission levels.

Setting Up OCR for Additional Languages

The standard Docker image includes English OCR by default. To add other languages, Stirling PDF uses Tesseract language data files. These are downloaded automatically on first use if the container has internet access, or you can pre-download them into the tessdata volume.

# Create the tessdata directory
mkdir -p ~/stirling-pdf/stirling-data/tessdata

# Download language files directly into the volume
# Replace LANGCODE with the Tesseract language code (e.g. deu=German, fra=French, tur=Turkish)
curl -L "https://github.com/tesseract-ocr/tessdata/raw/main/LANGCODE.traineddata" \
  -o ~/stirling-pdf/stirling-data/tessdata/LANGCODE.traineddata

# Examples:
# German:  deu.traineddata
# French:  fra.traineddata
# Turkish: tur.traineddata
# Spanish: spa.traineddata
# Arabic:  ara.traineddata
# Chinese Simplified: chi_sim.traineddata

After downloading, restart the container. The OCR tool in Stirling PDF will show the new language in its dropdown automatically.

Accessing Stirling PDF Remotely with Localtonet

Stirling PDF's web interface runs on port 8080. When you are away from home or want colleagues to use the same instance, you need a way to reach port 8080 from the internet. A Localtonet HTTP tunnel creates a stable public HTTPS URL that forwards to your local port 8080, working even behind CGNAT or without a static IP.

chmod +x localtonet
sudo mv localtonet /usr/local/bin/
sudo localtonet authtoken YOUR_TOKEN

      - SYSTEM_FRONTENDURL=https://pdf.localto.net  # your Localtonet URL

sudo localtonet --install-service --authtoken YOUR_TOKEN
sudo localtonet --start-service --authtoken YOUR_TOKEN

Handling Large PDFs and File Size Limits

Stirling PDF itself supports files up to 2000 MB by default. If you are routing traffic through Localtonet's HTTP tunnel, large uploads work without any additional configuration because Localtonet does not impose upload size limits.

If you are putting Stirling PDF behind a separate reverse proxy (Nginx, Caddy, Nginx Proxy Manager), you need to adjust the proxy's upload limit. For Nginx:

client_max_body_size 500M;
proxy_read_timeout 300s;
proxy_send_timeout 300s;

To change the maximum file size inside Stirling PDF itself:

      - SYSTEM_MAXFILESIZE=500                           # MB
      - SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE=500MB
      - SPRING_SERVLET_MULTIPART_MAX_REQUEST_SIZE=500MB

Using the REST API

Every tool in Stirling PDF has a corresponding REST API endpoint. This is useful for automating PDF processing in scripts, CI/CD pipelines, or applications. The full interactive API documentation is available at http://YOUR-SERVER:8080/swagger-ui/index.html.

# Merge two PDFs
curl -X POST "http://localhost:8080/api/v1/general/merge-pdfs" \
  -F "fileInput=@document1.pdf" \
  -F "fileInput=@document2.pdf" \
  -o merged.pdf

# OCR a scanned PDF (add searchable text layer)
curl -X POST "http://localhost:8080/api/v1/misc/ocr-pdf" \
  -F "fileInput=@scanned.pdf" \
  -F "languages=eng" \
  -o ocr-output.pdf

# Compress a PDF
curl -X POST "http://localhost:8080/api/v1/general/compress-pdf" \
  -F "fileInput=@large.pdf" \
  -F "optimizeLevel=3" \
  -o compressed.pdf

# Convert DOCX to PDF (requires latest image with LibreOffice)
curl -X POST "http://localhost:8080/api/v1/convert/file/pdf" \
  -F "fileInput=@document.docx" \
  -o document.pdf

# Check server status
curl http://localhost:8080/api/v1/info/status

Running on Raspberry Pi (Ultra-Lite Image)

On a Raspberry Pi or any machine with limited RAM, use the ultra-lite image. It runs with as little as 1 GB RAM and starts significantly faster than the full image:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest-ultra-lite
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
    environment:
      - TZ=Europe/Istanbul
      - SECURITY_ENABLELOGIN=false
      - LANGS=en_GB
    mem_limit: 1g    # optional: cap memory usage

The ultra-lite image excludes OCR (Tesseract) and document conversion (LibreOffice). You still get: merge, split, compress, rotate, reorder pages, add watermarks, add page numbers, remove passwords, add passwords, flatten, and all other operations that work on PDF structure directly. For most everyday PDF tasks, this is sufficient.

Updating to a New Version

cd ~/stirling-pdf

# Pull the latest image
docker compose pull

# Recreate the container with the new image
docker compose up -d

# Verify the new version
curl http://localhost:8080/api/v1/info/status

Stirling PDF is stateless — no persistent data lives inside the container. Your configs, OCR language files, and pipeline configurations are all in the mounted volumes and are unaffected by container updates. There is no database migration to worry about for standard deployments.

Troubleshooting Common Problems

Frequently Asked Questions