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
8080is the app's HTTP port. In this guide it binds to127.0.0.1:8080so only a reverse proxy on the same host can reach it. - One persistent volume:
/configsinside 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=trueon any internet-facing instance. Disabling it turns the app into an open PDF processor. - Leave
SYSTEM_ENABLEANALYTICS=falseandSYSTEM_GOOGLEVISIBILITY=falseunless you explicitly want outbound telemetry. - Set
SYSTEM_MAXFILESIZEto 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:
- Upload limits bite twice. If the reverse proxy caps bodies at 1 MB (Nginx default) while
SYSTEM_MAXFILESIZEis 100 MB, large PDFs fail with a 413 before Stirling PDF ever sees them. Align both numbers. - The
/configsvolume 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/.

