Stirling PDF

Last reviewed Aug 23, 2026 · 627 words

Stirling PDF exists to answer one question: why are you uploading your lease, your payslip, or your kid's medical form to freepdfconverter-totally-legit.com? It puts fifty-odd PDF tools — merge, split, compress, convert, OCR, redact, sign, watermark — behind one web page on your own server, where documents are processed locally and never leave the box. It's the highest usefulness-per-setup-minute ratio in this directory: one container, no database, no accounts required.

The five-minute install

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    ports:
      - "8081:8080"
    environment:
      - LANGS=en_GB
    volumes:
      - ./trainingData:/usr/share/tessdata
      - ./configs:/configs
    restart: unless-stopped

That's the whole thing. Stirling is stateless by design — files are processed in memory and temp space, then discarded — so there's no data directory to protect and nothing meaningful to back up beyond the config folder. This also makes it the perfect "first service" for someone learning Docker: breaking it costs nothing, and the self-hosting 101 path pairs well with it.

Java memory: size it for your biggest document, not your average

The one operational fact worth knowing is the catalogue's listed con: it's a Java application, and PDF operations inflate in memory. The 512 MB minimum handles everyday documents; a 300-page scanned book being OCR'd or a 200 MB brochure being compressed can spike well past it, and an under-provisioned container dies mid-operation with an unhelpful error. Give it 1–2 GB of headroom (mem_limit: 2g if you cap containers) and the problem category disappears. Big-job slowness is normal — OCR is genuinely CPU-hungry — but crashing is always memory.

OCR needs its languages installed

The OCR tool wraps Tesseract, and it only reads languages whose training data is present. English ships by default; for anything else, drop the relevant .traineddata files into the mounted trainingData folder (German is deu, French fra, and so on) and select them in the OCR tool. The same rule as Paperless-ngx: OCR in the wrong language produces text that looks indexed and never matches a search. Which raises the boundary worth drawing — Stirling transforms documents; it doesn't file them. If what you actually want is a searchable archive of your paperwork, that's Paperless-ngx's job, and the two are natural neighbours: Stirling for the one-off surgery (split the scan, fix the rotation, OCR the old file), Paperless for the permanent archive.

Exposure and the login switch

Default Stirling has no authentication — fine on a LAN, not fine on the internet, where an open instance is free compute plus a privacy hole for anyone who finds it. If the household uses it at home, leave it LAN-only or behind Tailscale and skip logins entirely; friction kills adoption of exactly the tool meant to replace convenient sketchy websites. If you do publish it, enable the built-in login (SECURITY_ENABLE_LOGIN=true plus an initial username/password in the environment) or put your reverse proxy's auth in front. Pipelines and the API (the same tools, scriptable — batch-compressing a folder of scans is a one-liner) inherit whatever exposure you chose, so decide deliberately.

What I'd do

Deploy the compose file above with 2 GB of memory headroom, add your languages' Tesseract data, bookmark it as the household's "PDF thing", and keep it LAN/VPN-only with no login. Then delete the bookmark folder of online converter sites — that's the actual migration. Of everything in this directory, Stirling is the app I'd recommend to someone who has never self-hosted anything: visible value in the first ten minutes, zero maintenance debt afterward.