Deploy Stirling PDF on a VPS

Stirling PDF is a self-hosted, all-in-one PDF toolbox (merge, split, compress, convert, OCR, watermark, sign, etc.) with a web UI and API. This guide deploys it via Docker.

1. Prerequisites

• A RamNode VPS with at least 2 vCPUs / 2 GB RAM (OCR and large PDF conversions benefit from more)
• Ubuntu 22.04/24.04
• (Optional) a domain name for HTTPS access

2. Initial server setup

ssh youruser@your-vps-ip
sudo apt update && sudo apt upgrade -y
sudo timedatectl set-timezone UTC

Firewall:

sudo apt install -y ufw
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

3. Install Docker and Docker Compose

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

4. Create the project directory

mkdir -p ~/stirling-pdf/{data,config,logs,pipeline}
cd ~/stirling-pdf

5. Create the Docker Compose file

nano docker-compose.yml

Paste (using the "full" image, which includes OCR language packs and LibreOffice for conversions — recommended unless you want a minimal footprint):

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest-fat
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/usr/share/tessdata
      - ./config:/configs
      - ./logs:/logs
      - ./pipeline:/pipeline
    environment:
      - DOCKER_ENABLE_SECURITY=false
      - LANGS=en_GB,en_US
      - SYSTEM_DEFAULTLOCALE=en-US
      - UI_APPNAME=Stirling PDF
      - UI_HOMEDESCRIPTION=Your Local PDF Toolkit
      - SYSTEM_MAXFILESIZE=100

Notes:

• stirlingtools/stirling-pdf:latest-fat (formerly -full) bundles OCR (Tesseract) and Office conversion (LibreOffice). Use stirlingtools/stirling-pdf:latest for a lighter image without those features if you don't need them.
• DOCKER_ENABLE_SECURITY=false disables the built-in login/auth system — fine if you're putting this behind your own reverse-proxy auth or only accessing it over a private network. Set to true and configure SECURITY_ENABLELOGIN if you want Stirling's own user accounts (see step 7).
• SYSTEM_MAXFILESIZE is in MB — raise it if you work with large PDFs.

6. Launch it

docker compose up -d
docker compose logs -f

Visit http://your-vps-ip:8080 to reach the Stirling PDF UI.

7. (Optional) Enable built-in authentication

If you want Stirling's own login page instead of relying solely on a reverse proxy:

    environment:
      - DOCKER_ENABLE_SECURITY=true
      - SECURITY_ENABLELOGIN=true

Recreate the container:

docker compose up -d

On first visit you'll be prompted to set an admin username and password.

8. Put it behind a reverse proxy with HTTPS

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

/etc/caddy/Caddyfile:

pdf.yourdomain.com {
    reverse_proxy localhost:8080
}

sudo systemctl restart caddy
sudo ufw delete allow 8080

9. Using the API

Stirling PDF exposes a REST API alongside the UI, documented at /swagger-ui/index.html on your instance (e.g., https://pdf.yourdomain.com/swagger-ui/index.html). Example — merge two PDFs via curl:

curl -X POST https://pdf.yourdomain.com/api/v1/general/merge-pdfs \
  -F "fileInput=@doc1.pdf" \
  -F "fileInput=@doc2.pdf" \
  -o merged.pdf

10. Updating

cd ~/stirling-pdf
docker compose pull
docker compose up -d

11. Backups

The only stateful data worth backing up is your config directory (settings) and, if you enabled login, the internal user database it creates there:

tar czf stirling-pdf-backup-$(date +%F).tar.gz ~/stirling-pdf/config ~/stirling-pdf/data