x
Skip to main content
Version: 2.0 (Beta)

Docker Installation for Stirling-PDF

Run Stirling-PDF in Docker for easy self-hosting, automatic updates, and flexible deployment.

Quick Start​

docker run -d \
  --name stirling-pdf \
  -p 8080:8080 \
  -v ./stirling-data:/configs \
  stirlingtools/stirling-pdf:latest

Then open http://localhost:8080 in your browser!

Choosing Your Version​

Stirling-PDF offers three versions depending on your needs:

VersionTagWhat's IncludedBest For
StandardlatestAll PDF featuresMost users, balanced features & size
Fatlatest-fatEverything + extra toolsMaximum features, larger container
Ultra-Litelatest-ultra-liteCore features onlyLimited resources, minimal size

Most users should use latest - it has everything you need.

When to use each version:​

Standard (latest) - Use this if:

  • ✅ You want all PDF features
  • ✅ You have normal server/computer specs
  • ✅ You're not sure which to pick

Fat (latest-fat) - Use this if:

  • 📦 You need every possible conversion format
  • 📦 You want all optional tools included
  • 📦 Disk space isn't a concern

Ultra-Lite (latest-ultra-lite) - Use this if:

  • 💾 Running on very limited hardware (Raspberry Pi, low-end VPS)
  • 💾 Want fastest startup time
  • 💾 Only need basic PDF operations

To use a different version, just change the tag:

docker run -d stirlingtools/stirling-pdf:latest-ultra-lite

Deployment Options (V2.0+)​

V2.0 lets you run Stirling-PDF in different ways depending on your needs:

MODE=BOTH (Default) - Everything in one container

  • ✅ Easiest setup - One container does it all
  • ✅ Perfect for most users - Single server hosting
  • ✅ No extra configuration - Works out of the box
docker run -d \
  --name stirling-pdf \
  -p 8080:8080 \
  -e MODE=BOTH \
  stirlingtools/stirling-pdf:latest

Use this if: You're running on a single server and want the simplest setup.

Advanced Deployment (Split Frontend/Backend)​

For advanced users who need to scale components independently:

MODE=BACKEND - Backend API only

  • Runs the PDF processing API server
  • Multiple frontends can connect to one backend
  • Scale processing power independently

MODE=FRONTEND - Frontend only

  • Serves the React web interface
  • Can be deployed to CDN for global distribution
  • Multiple instances for load balancing

Use split mode if:

  • Scaling frontend and backend independently
  • CDN deployment for global frontend distribution
  • Running multiple frontend instances with shared backend
  • Microservices/containerized architecture

V2.0 Configuration Variables​

VariableWhat It DoesWhen You Need ItExample
MODEDeployment typeAlways (defaults to BOTH)MODE=BOTH
BACKEND_INTERNAL_PORTInternal backend portOnly for MODE=BOTH customizationBACKEND_INTERNAL_PORT=8081
VITE_API_BASE_URLWhere the backend is locatedRequired for MODE=FRONTENDVITE_API_BASE_URL=http://backend:8080

Most users don't need to set these - the defaults work great!

Full Setup (With All Features)​

Want OCR, custom settings, and logging? Add more volumes:

docker run -d \
  --name stirling-pdf \
  -p 8080:8080 \
  -v ./stirling-data/tessdata:/usr/share/tessdata \
  -v ./stirling-data/configs:/configs \
  -v ./stirling-data/logs:/logs \
  -v ./stirling-data/pipeline:/pipeline \
  -e SECURITY_ENABLELOGIN=false \
  -e LANGS=en_GB \
  stirlingtools/stirling-pdf:latest

What each volume does:

  • /configs - Your settings and database
  • /usr/share/tessdata - OCR language files
  • /logs - Application logs
  • /pipeline - Automation configurations

What this does:

  • Runs Stirling-PDF on port 8080
  • Stores data in ./stirling-data folder
  • Automatically restarts if it crashes
  • Everything in one container (MODE=BOTH is default)

Split Deployment (Advanced Users)​

Want to scale frontend and backend independently? Use this:

Create docker-compose.yml:

version: '3.3'
services:
  # Backend - PDF processing engine
  stirling-backend:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-backend
    ports:
      - '8081:8080'
    volumes:
      - ./stirling-data/tessdata:/usr/share/tessdata
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/pipeline:/pipeline
    environment:
      - MODE=BACKEND                    # Backend only
    restart: unless-stopped

  # Frontend - Web interface
  stirling-frontend:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-frontend
    ports:
      - '8080:8080'
    environment:
      - MODE=FRONTEND                               # Frontend only
      - VITE_API_BASE_URL=http://stirling-backend:8080  # Where backend is located
    depends_on:
      - stirling-backend
    restart: unless-stopped

Benefits of split deployment:

  • Scale frontend and backend independently
  • Run multiple frontends with one backend
  • Deploy frontend globally via CDN
  • Better resource allocation

When to use split:

  • High traffic websites
  • Global user base
  • Microservices architecture
  • Need independent scaling

Updating Stirling-PDF​

Docker Run​

docker stop stirling-pdf
docker rm stirling-pdf
docker pull stirlingtools/stirling-pdf:latest
# Then run your original docker run command

Docker Compose​

docker-compose down
docker-compose pull
docker-compose up -d

Your data is safe in the volumes and will persist across updates!

Common Configurations​

Enable User Authentication​

environment:
  - SECURITY_ENABLELOGIN=true

Change Interface Language​

environment:
  - LANGS=es_ES  # Spanish, or en_GB, fr_FR, de_DE, etc.

Multiple Languages​

environment:
  - LANGS=en_GB,es_ES,fr_FR  # Comma-separated

Custom Port​

ports:
  - '9000:8080'  # Access at http://localhost:9000

Next Steps​

Troubleshooting​

Can't access at localhost:8080?

  • Check if port 8080 is already in use
  • Try a different port: -p 9000:8080
  • Check firewall settings

Permission errors with volumes?

  • Make sure the directories exist
  • Check folder permissions: chmod -R 755 ./stirling-data

Container keeps restarting?

  • Check logs: docker logs stirling-pdf
  • Check system resources (RAM, disk space)
  • Try ultra-lite version for limited hardware

Features not working?

  • Some features need dependencies
  • Check logs for missing requirements
  • Consider using latest-fat for all features