How to Install Stirling-PDF on Docker

Have you ever felt hesitant when you had to upload sensitive company documents or personal data to some random “Free PDF Converter” website just to merge two pages? Or perhaps you’re tired of the ever-increasing licensing costs of commercial PDF editor software each year? Data privacy and cost efficiency are two major challenges in digital document management. The best solution to address these issues is to self-host your own PDF management tools.

Introducing Stirling-PDF, a Swiss Army Knife for PDF manipulation that you can run on your own server. This article will guide you through its features and walk you step-by-step through deploying it on an Ubuntu server.

What is Stirling-PDF?

Stirling-PDF is an open-source, web-based PDF manipulation application. It combines various PDF functionalities—usually scattered across multiple tools—into a single modern and intuitive user interface (UI).

The main advantage of Stirling-PDF lies in data sovereignty. All file processing is performed locally on your server. No files are sent to third-party servers, making it an ideal solution for organizations with strict data privacy compliance standards (GDPR, HIPAA, etc.).

Key Features of Stirling-PDF

Why does the open-source community love Stirling-PDF so much? Here are its key features:

• Page Manipulation: Merge, split, rotate, and reorder PDF pages.
• Format Conversion: Convert PDF to images, images to PDF, PDF to Word/HTML, and vice versa.
• Security: Add passwords, remove passwords, apply digital signatures, and add watermarks.
• OCR (Optical Character Recognition): Convert scanned PDFs into searchable and copyable text.
• Edit & Compression: Add text/image overlays and reduce PDF file size.
• Modern UI: Supports Dark Mode and a responsive interface.

System Requirements

Stirling-PDF runs inside a Docker container, so its requirements are fairly flexible. However, for smooth performance—especially when using OCR features—here are the recommendations:

• CPU: Minimum 2 vCPU (OCR requires significant processing power).
• RAM: Minimum 2 GB (4 GB recommended for production).
• Disk: 10 GB of free space (for Docker images and temporary files).

This tutorial uses Ubuntu LTS as the operating system.

Stirling-PDF Installation Guide on Ubuntu

We will deploy Stirling-PDF using Docker Compose and prepare it for production with an Nginx Reverse Proxy and SSL.

Server Preparation

First, make sure your system is up to date and install the basic dependencies: Docker, Docker Compose, Nginx, and Certbot.

sudo apt update && sudo apt upgrade -y
sudo sh -c "curl -fsSL https://get.docker.com/ | sh"
sudo apt install nginx certbot python3-certbot-nginx -y

Installing Stirling-PDF with Docker Compose

The best way to manage Stirling-PDF is by using Docker Compose.

Create a working directory:

mkdir stirling-pdf
cd stirling-pdf

Create the docker-compose.yml file:

nano docker-compose.yml

Insert the following configuration:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - '8080:8080'
    volumes:
      # Persistent data storage
      - ./stirling-data/tessdata:/usr/share/tessdata     # OCR language files
      - ./stirling-data/configs:/configs                 # Settings & database
      - ./stirling-data/logs:/logs                       # Application logs
      - ./stirling-data/customFiles:/customFiles:rw      # Custom branding files
      - ./stirling-data/pipeline:/pipeline               # Automation configs
    environment:
      # Core Settings
      - SECURITY_ENABLELOGIN=true            # Enable user authentication

      # Language & Localization
      - LANGS=en_GB                          # Change to your locale

      # System Configuration
      - SYSTEM_DEFAULTLOCALE=en-GB           # Default locale
      - SYSTEM_GOOGLEVISIBILITY=false        # Hide from search engines
      - SYSTEM_ROOTURIPATH=/                 # Base URL path
      - SYSTEM_CONNECTIONTIMEOUTMINUTES=5    # Connection timeout
      - SYSTEM_MAXFILESIZE=2000              # Max file size in MB

      # Optional: Logging
      - SYSTEM_CUSTOMSTATICFILEPATH=/customFiles/static/  # Custom files path

    restart: unless-stopped

    # Optional: Resource limits
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2.0'
        reservations:
          memory: 2G
          cpus: '1.0'

Run Stirling-PDF:

sudo docker compose up -d

Verify the installation by checking the container status:

sudo docker compose ps

If the status is Up, the application is running at http://IP-Your-Server:8080.

NAME           IMAGE                               COMMAND                  SERVICE        CREATED          STATUS          PORTS
stirling-pdf   stirlingtools/stirling-pdf:latest   "tini -- /scripts/in..."   stirling-pdf   30 seconds ago   Up 28 seconds   0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp

Nginx Reverse Proxy Configuration

To make the application accessible via a domain (e.g., pdf.yourdomain.com) and support large file uploads, we need to configure Nginx.

Create a server block configuration file:

sudo nano /etc/nginx/sites-available/pdf.yourdomain.com.conf

Insert the following configuration (adjust server_name accordingly):

server {
    listen 80;
    server_name pdf.yourdomain.com;

    # Log files
    access_log /var/log/nginx/stirling_access.log;
    error_log /var/log/nginx/stirling_error.log;

    # IMPORTANT: Allow large file uploads (example: 100MB)
    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;

        # Timeout configuration for heavy processes like OCR
        proxy_read_timeout 300s;
        proxy_connect_timeout 300s;
    }
}

Enable the configuration:

sudo ln -s /etc/nginx/sites-available/pdf.yourdomain.com.conf /etc/nginx/sites-enabled/

Check syntax and restart Nginx:

sudo nginx -t
sudo systemctl restart nginx

SSL Installation with Certbot

The final step is securing the connection with HTTPS so uploaded documents are encrypted.

sudo certbot --non-interactive \
-m [email protected] \
--agree-tos \
--no-eff-email \
--nginx -d pdf.yourdomain.com \
--redirect

Stirling-PDF is now accessible at https://pdf.yourdomain.com. Log in with username = admin and password = stirling.

Conclusion

Congratulations! You now have Stirling-PDF running entirely on your own server. You can access it via https://pdf.yourdomain.com and start processing documents securely. With this setup, you not only reduce IT operational costs but also ensure the privacy and security of your organization’s documents. Stirling-PDF proves that open-source solutions can compete with—and even surpass—commercial solutions in terms of flexibility and security.