2026-11-18 · pdf · docker · self-hosting · productivity
Self-Host Stirling PDF with Docker: Private PDF Toolkit
Run Stirling PDF in Docker for private PDF editing, merging, OCR, and conversion. Covers compose setup, reverse proxy, backups, and hardening.
- Total RAM
- 989.5 MB
- Startup
- 238.1 s
- Port
- 8080
- HTTP
- 200
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.