How to Deploy Stirling-PDF on a VPS

#Install Stirling-PDF (Docker Compose)

The upstream Docker guide documents four bind mounts: /configs for settings and the user database, /logs, /pipeline for saved automations, and /usr/share/tessdata for extra OCR languages. This guide keeps the first three and leaves tessdata to the image, so the bundled OCR data stays in place; add that mount later only if you need more languages.

copymkdir -p ~/stirling-pdf/stirling-data/{configs,logs,pipeline}
cd ~/stirling-pdf
cat > docker-compose.yml <<'YAML'
services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      # Loopback only: Caddy is the only way in from outside.
      - "127.0.0.1:8080:8080"
    volumes:
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/pipeline:/pipeline
    environment:
      SYSTEM_DEFAULTLOCALE: en-US
YAML
docker compose up -d

Java takes a little while to start. Wait until the web UI answers — with login enabled, the root URL either serves the app or redirects to the login page:

copyfor i in $(seq 1 60); do
  code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8080/)
  case "$code" in 200|302) echo "Stirling-PDF is up ($code)"; break ;; esac
  sleep 5
done
case "$code" in 200|302) true ;; *) docker compose logs --tail 50; false ;; esac

#First login: change the default password

Per the upstream docs, a fresh container starts with login enabled and a default admin account:

• Username: admin
• Password: stirling

Change this password immediately after first login. Anyone who can reach the instance before you do can sign in with those credentials, which is another reason to keep port 8080 on loopback and only expose the app through HTTPS once you're ready to log in straight away.

From the admin account you can add more users under the account settings. If you truly want a single-user tool with no authentication — for example, reachable only over a VPN — upstream lets you opt out with SECURITY_ENABLELOGIN=false. Don't do that on an instance with a public hostname.

#HTTPS + domain

Point an A record such as pdf.example.com at the server and terminate TLS in front of 127.0.0.1:8080, following Automatic HTTPS with Caddy:

pdf.example.com {
    request_body {
        max_size 200MB
    }
    reverse_proxy 127.0.0.1:8080
}

The request_body block keeps Caddy from rejecting large uploads; pick a limit that matches the files you work with. Stirling-PDF has its own upload limit too: SYSTEM_MAXFILESIZE (in MB) appears in the upstream example Compose files. If Caddy runs as a container rather than on the host, 127.0.0.1 is the proxy's own loopback — put both services in one Compose project and use reverse_proxy stirling-pdf:8080.

#Using it

The web UI lists the tools by category; files are processed and handed back to you, not stored. A few features worth knowing:

• Pipelines (the "Automate" feature) chain operations — for example OCR, then compress, then add a watermark — and save them for reuse. Saved pipelines live in the /pipeline mount.
• The REST API exposes the same operations, so scripts and other services can call it. The API documentation is linked from the project's README.
• Language: SYSTEM_DEFAULTLOCALE sets the default UI language (for example de-DE or fr-FR); unset, it follows the browser.

Stirling-PDF pairs well with a document archive: clean up, merge or redact a file here, then file it in Paperless-ngx.

#Securing it

• Change admin / stirling on first login — this is the only mandatory step.
• Keep login enabled on anything with a public hostname, and create individual accounts rather than sharing the admin login.
• Keep the port on loopback. ss -ltnp | grep 8080 should show 127.0.0.1:8080.
• Patch it. Upstream's update procedure is simply pulling the image again; do it on a schedule (see Upgrades).

#Backups

Processed files aren't kept, so the only state is stirling-data: settings, the user database and an encryption key in configs, plus your saved pipelines. On start the container takes ownership of the mounted folders for its own user, and some files (the credential encryption key among them) are readable only by that user — so archive with sudo, or the backup silently misses them. Stop the container for a consistent copy, archive the directory, and start it again:

copycd ~/stirling-pdf
docker compose stop
sudo tar czf stirling-pdf-$(date +%F).tar.gz docker-compose.yml stirling-data
docker compose start
sudo tar tzf stirling-pdf-$(date +%F).tar.gz | grep credential-encryption.key

Copy the archive off the server. Restoring is the reverse: extract it into ~/stirling-pdf on a new box and run docker compose up -d.

#Upgrades

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

The latest tag moves with each release; your settings and accounts survive because they live in the bind mounts. Back up stirling-data first and read the release notes before a major version — upstream publishes a migration guide for the v1-to-v2 change, where several settings were renamed.

#Troubleshooting

The page doesn't load right after starting. Give Java a minute; watch docker compose logs -f stirling-pdf for the startup message.

The container keeps restarting. Upstream's advice: check the logs, check free RAM and disk, and try the latest-ultra-lite image on limited hardware.

Permission errors on the mounted folders. The directories must exist and be writable by the container's user. Creating them before the first start, as above, avoids root-owned folders. Afterwards they belong to the container's user, so use sudo to read or copy them from the host.

Uploads fail on big files. Raise Caddy's request_body limit and, if needed, SYSTEM_MAXFILESIZE.

#Verification + next steps

You're done when you can load https://pdf.example.com over a valid certificate, log in with your new admin password (the old one no longer works), merge two PDFs and download the result, and you have a copy of stirling-data off the box.

Next, save a pipeline for the operation you repeat most, and create accounts for anyone else who will use it. For hosts, see Best VPS for Self-Hosting.