VPSFolio

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.

Bench run · 2026-11-18 Verified
Stirling-Tools/Stirling-PDF
Total RAM
989.5 MB
Startup
238.1 s
Port
8080
HTTP
200
docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest · 1 container · Stirling-Tools/Stirling-PDF

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.