This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.

What Stirling PDF does and what it needs

Stirling PDF is a self-hosted web app that bundles 50+ PDF tools behind one UI and a REST API: merge, split, compress, OCR, sign, redact, convert to/from Office formats, and more. Documents never leave your server. The upstream project ships a single container image (docker.stirlingpdf.com/stirlingtools/stirling-pdf) that listens on port 8080 and stores its working data under /configs.

The project does not publish a minimum RAM figure. Practical memory use scales with workload: idle browsing is light, while OCR, large merges, and batch conversions are CPU- and memory-heavy. Size the box for the heaviest job you expect to run.

Prerequisites, ports, and volume constraints

  • Docker Engine 24+ and the Compose plugin.
  • Port 8080 is the app's HTTP port. In this guide it binds to 127.0.0.1:8080 so only a reverse proxy on the same host can reach it.
  • One persistent volume: /configs inside the container. It holds settings, custom fonts, pipeline configs, and generated output. Back it up; losing it means reconfiguring from scratch.
  • No database or cache container is required. Stirling PDF is stateless apart from /configs.
  • If you plan to expose it publicly, terminate TLS at a reverse proxy and keep the container on localhost.

Production Docker Compose setup

Create a project directory and drop in the compose file and .env.

mkdir -p ~/stirling-pdf && cd ~/stirling-pdf cat <<'EOF' > compose.yml services: stirling-pdf: image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest container_name: stirling-pdf restart: unless-stopped ports: - "127.0.0.1:8080:8080" environment: TZ: ${TZ:-UTC} SECURITY_ENABLELOGIN: ${SECURITY_ENABLELOGIN:-true} SECURITY_INITIALLOGIN_USERNAME: ${SECURITY_INITIALLOGIN_USERNAME:-admin} SECURITY_INITIALLOGIN_PASSWORD: ${SECURITY_INITIALLOGIN_PASSWORD} SYSTEM_DEFAULTLOCALE: ${SYSTEM_DEFAULTLOCALE:-en-US} SYSTEM_MAXFILESIZE: ${SYSTEM_MAXFILESIZE:-100} SYSTEM_GOOGLEVISIBILITY: ${SYSTEM_GOOGLEVISIBILITY:-false} SYSTEM_ENABLEANALYTICS: ${SYSTEM_ENABLEANALYTICS:-false} volumes: - stirling-configs:/configs healthcheck: test: ["CMD-SHELL", "curl -fsS http://localhost:8080/ || exit 1"] interval: 30s timeout: 10s retries: 5 volumes: stirling-configs: EOF 

Generate secrets and write .env:

cat <<EOF > .env TZ=UTC SECURITY_ENABLELOGIN=true SECURITY_INITIALLOGIN_USERNAME=admin SECURITY_INITIALLOGIN_PASSWORD=$(openssl rand -hex 24) SYSTEM_DEFAULTLOCALE=en-US SYSTEM_MAXFILESIZE=100 SYSTEM_GOOGLEVISIBILITY=false SYSTEM_ENABLEANALYTICS=false EOF chmod 600 .env 

Start the stack:

docker compose up -d docker compose logs -f stirling-pdf 

Open http://127.0.0.1:8080 from the host (or via SSH tunnel: ssh -L 8080:127.0.0.1:8080 user@server) and log in with the credentials from .env. Change the password immediately after first login.

Reverse proxy, HTTPS, and first-run hardening

Stirling PDF serves plain HTTP and does not need WebSocket upgrades for its core tools. A standard reverse proxy with a generous upload limit is enough. Example Caddyfile:

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

For Nginx, set client_max_body_size 200M; and proxy to http://127.0.0.1:8080. Keep the container bound to localhost so the app is never reachable over plain HTTP on the public IP.

First-run hardening checklist:

  • Log in with the generated admin password, then change it under account settings.
  • Keep SECURITY_ENABLELOGIN=true on any internet-facing instance. Disabling it turns the app into an open PDF processor.
  • Leave SYSTEM_ENABLEANALYTICS=false and SYSTEM_GOOGLEVISIBILITY=false unless you explicitly want outbound telemetry.
  • Set SYSTEM_MAXFILESIZE to match the proxy body limit so users get a clean error instead of a truncated upload.
  • If you only need it occasionally, skip the public DNS record and use an SSH tunnel.

Updating, backups, and common pitfalls

Update to the latest image:

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

Back up the config volume (named stirling-configs in the compose file above):

docker run --rm \ -v stirling-configs:/data \ -v "$PWD":/backup \ alpine tar czf /backup/stirling-configs-$(date +%F).tar.gz -C /data . 

Restore by extracting the archive back into a fresh stirling-configs volume before starting the stack.

Two pitfalls worth knowing:

  1. Upload limits bite twice. If the reverse proxy caps bodies at 1 MB (Nginx default) while SYSTEM_MAXFILESIZE is 100 MB, large PDFs fail with a 413 before Stirling PDF ever sees them. Align both numbers.
  2. The /configs volume is the whole state. Wiping it loses login credentials, custom fonts, and saved pipelines. Treat it like a database volume: back it up before every major version bump, and never bind-mount it from an ephemeral path.

Measured in our sandbox run: total memory 989.5 MB (sum of per-container peaks over a 30s idle window after startup) across 1 container; largest container 989.5 MB; published port(s) 8080; HTTP probe returned 200. The run took 238.1s including the image download. Required secret(s) SECURITY_INITIALLOGIN_PASSWORD were generated for the test run, as the tutorial instructs.

Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.

Originally published with full interactive benchmark metrics and server sizing notes at https://benchrun.pages.dev/stirling-pdf-docker-self-hosting/.