Stirling PDF: Every PDF Tool You've Googled, Self-Hosted

Search “merge pdf free” and you get a page of nearly identical sites, all offering to combine your files for free, all quietly uploading whatever you drop on them to a server you know nothing about. Most of these sites are legitimate businesses funded by ads and “premium” upsells rather than anything malicious, but legitimate doesn’t mean “you should upload your signed tenancy agreement, your child’s passport scan, or a client contract to it.” I stopped doing that the day I actually read one of these sites’ privacy policies and found a data-retention clause I couldn’t parse in under a lawyer’s fee. Stirling PDF is the tool that made me never need to again — it’s every one of those single-purpose web tools, bundled into one self-hosted app, running entirely on hardware I control.

Stirling PDF is an open-source, self-hosted web application — a Spring Boot backend with a browser-based frontend — that bundles roughly 50 distinct PDF operations behind one interface: merge, split, compress, rotate, watermark, add or remove passwords, convert to and from images and Office formats, OCR scanned pages, redact text, add digital signatures, and more. Every operation runs locally in your container. Nothing leaves your network unless you deliberately export the result somewhere.

Why this is a privacy problem worth solving

PDFs are where sensitive documents concentrate: contracts, medical letters, tax paperwork, ID scans, signed agreements. The free-web-tool ecosystem around basic PDF operations exists because these are genuinely common, genuinely annoying tasks — almost everyone hits “I need to merge four scanned pages into one file” sooner or later — and the convenience trade is worse than it looks. Most of these sites’ business models depend on either ad revenue funded by whatever they can infer about you, or a freemium upsell, and more than a few have had their file-retention practices called into question by security researchers over the years — files that were supposed to be deleted after processing found still sitting on public-facing storage.

You don’t need to assume malice to want out of that trade. You just need to notice that “upload a document to a server, trust it gets deleted” is a worse privacy posture than “process the document on hardware you already own,” and that the second option now costs about the same ten minutes of setup as the first costs in reading a privacy policy you were never going to finish anyway.

There’s also a category of document that shouldn’t touch a third-party server even under a generous reading of that party’s intentions, regardless of how trustworthy the operator turns out to be. A passport scan, a signed NDA, a medical referral letter — these carry consequences if they leak that go well beyond the inconvenience of most data breaches, because they’re the specific documents identity theft and targeted fraud are built from. The free-web-tool model can’t offer a guarantee that survives a single misconfigured storage bucket or a compromised employee account, no matter how sincerely worded its privacy policy is, and a homelab tool that never sends the file anywhere doesn’t need you to trust anyone’s intentions at all — there’s simply no third party in the loop to have intentions about.

Deploying it

Stirling PDF ships a single all-in-one image with every dependency (LibreOffice for conversions, Tesseract for OCR, qpdf for low-level manipulation) baked in, which makes the compose file almost suspiciously short:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# docker-compose.yml
services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - stirling-data:/usr/share/tessdata
      - stirling-config:/configs
      - stirling-logs:/logs
    environment:
      - DOCKER_ENABLE_SECURITY=true
      - SECURITY_ENABLE_LOGIN=true
      - LANGS=en_GB,en,da
      - UI_APPNAME=PDF Tools
      - SYSTEM_DEFAULTLOCALE=en-GB
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/info/status"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  stirling-data:
  stirling-config:
  stirling-logs:

DOCKER_ENABLE_SECURITY=true plus SECURITY_ENABLE_LOGIN=true turns on Stirling’s built-in authentication layer — without it, the app is wide open to anyone who can reach the port, which is fine on a strictly local network but not something to expose further. First boot creates a default admin/stirling login that the UI forces you to change immediately; don’t skip that step if this is reachable from anywhere beyond your own machine.

LANGS controls which Tesseract OCR language packs get installed — only pull the ones you’ll actually use, since each adds real image size and a scanned-document OCR job will list every installed language as an option whether you want it there or not.

Put it behind a reverse proxy for TLS if you want it reachable outside your LAN — see Reverse Proxy Done Right — though for a tool that handles this category of sensitive document, I’d lean toward Tailscale-only access over a public hostname, the same call I’d make for anything touching identity documents.

The operations that actually replace paid software

A handful of Stirling’s tools are worth calling out specifically because they replace software people pay real subscription money for:

• OCR (Tesseract under the hood) turns a scanned, non-searchable PDF into one with an invisible text layer, so you can select and search text in a document that started as a flat image. This is the same core capability Paperless-ngx uses for its document archive, but Stirling gives you a one-off tool for a single file without standing up a full document-management system.
• Redaction does a real content-level black-out — it removes the underlying text and image data in the redacted region rather than just drawing a black box over it, which matters because the “just draw a black rectangle” approach used by some PDF viewers leaves the original text perfectly recoverable by selecting and copying it. This distinction has caused actual public redaction failures in the wild; Stirling’s redaction tool strips the underlying content itself.
• Compress re-encodes embedded images and can flatten a bloated 40 MB scan into a few megabytes with a quality slider, useful for anything with an upload size limit.
• Compare diffs two PDFs and highlights textual differences, handy for catching what changed between two versions of a contract without reading both side by side.
• Digital signing adds a certificate-based signature, distinct from just pasting an image of your signature onto a page — it’s a genuine cryptographic signature that can be verified against a certificate, the same category of feature Adobe charges a subscription for.

Automating it: the API

Every operation in the UI is also a REST endpoint, documented via Swagger at /swagger-ui/index.html on your instance. That means Stirling is fully scriptable on top of the manual UI:

1
2
3
4
5
6
7

# Merge three PDFs via the API, saving the result locally
curl -X POST http://stirling.example.com:8080/api/v1/general/merge-pdfs \
  -H "Authorization: Bearer ${STIRLING_API_KEY}" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o q1-merged.pdf

I have this wired into a small script that merges a month’s worth of scanned receipts into one file on the first of every month, which is the kind of thing that used to mean either doing it manually in a paid PDF app or, worse, uploading a folder of receipts to a web tool one at a time.

The forms and conversion tools

Beyond the headline merge/split/OCR set, two quieter tool categories earn their place. The form tools let you extract fillable form fields from a PDF into flat data, or flatten a filled-in form so the field values become permanent page content rather than editable inputs — useful once a form has been signed and needs to stop being editable before it’s archived. The conversion tools go both directions between PDF and Word/Excel/PowerPoint/images/HTML, backed by the bundled LibreOffice instance, so a scanned contract can become an editable Word document, or a spreadsheet can become a shareable PDF, without opening a separate office suite at all.

There’s also a pipeline feature, less well known than the individual tools: you can chain several operations — say, OCR, then compress, then add a watermark — into a saved sequence and run a batch of files through all three steps in one pass via the UI’s automation tab. I use this for a recurring task: a folder of scanned invoices gets OCR’d, compressed, and watermarked with “ARCHIVED” in one click, instead of three separate manual passes through the tool.

Multi-user access without a shared login

Once more than one person in a household needs this, SECURITY_ENABLE_LOGIN on its own only gets you a single shared account, which is fine for a one-person deployment but starts to feel wrong the moment you’re sharing a password with a partner or a housemate — nobody can tell whose merge job is whose in the logs, and revoking access for one person means changing the password for everyone. Stirling’s newer versions support proper multi-user accounts with role-based permissions through the same security layer, so each person gets their own login and the admin account can restrict which tool categories a given user can reach — handing a read-only or conversion-only role to someone who only ever needs to turn a scan into a Word document, say, without giving them access to the signing or redaction tools. It’s a small feature next to the headline PDF operations, but it’s the difference between “a tool I run for myself” and “a tool the household actually uses,” and it’s the same reasoning that makes the credential-per-person model worth setting up on any shared self-hosted service rather than defaulting to one login everyone remembers.

Comparing it to the alternatives

The closest self-hosted comparison is running individual command-line tools — qpdf, pdftk, ocrmypdf, img2pdf — directly, which is more composable for scripting but has no UI at all, so it’s a poor fit for anyone else in a household who just wants to drag a file onto a page and click a button. Stirling sits in the gap between “raw CLI tools for people comfortable with a terminal” and “a paid desktop app like Adobe Acrobat,” giving the CLI tools’ privacy properties with the paid app’s usability, and its Swagger-documented API means the scripting use case isn’t actually lost — you get both interfaces over the same underlying operations.

Troubleshooting

OCR produces garbled or empty text layers. Almost always a language-pack mismatch — if LANGS doesn’t include the language actually in the scanned document, Tesseract does its best with the wrong dictionary and the output is unusable. Check the OCR tool’s language dropdown reflects what you set in LANGS, and rebuild the container after changing it since the language packs are pulled at image build/first-run time.

Large file uploads fail silently or time out. If you’re behind a reverse proxy, check its body-size and timeout limits before assuming Stirling itself is broken — Caddy and nginx both default to request size limits well under what a 100-page scanned PDF weighs. client_max_body_size in nginx or request_body limits in Caddy need raising for anything beyond casual document sizes.

“File processing failed” on LibreOffice-backed conversions (Word/Excel to PDF and back). These conversions shell out to a headless LibreOffice instance bundled in the image, which occasionally chokes on documents with unusual embedded fonts or macros. Check /logs (the mounted volume above) for the actual LibreOffice stderr — the UI error is generic, the log usually names the specific element it choked on.

Login page loops back to itself after entering correct credentials. Usually a cookie/session issue caused by mismatched baseUrl expectations when running behind a reverse proxy that rewrites paths. Make sure the proxy passes the Host header through unmodified and isn’t stripping a path prefix Stirling doesn’t know about.

Redaction tool leaves content in the file’s metadata or revision history. Stirling’s content redaction is thorough for the visible page content, but PDFs can carry other sensitive data — document metadata (author, editing history), embedded thumbnails, or attachments. Run the “Sanitise” operation after redacting, which strips metadata and embedded scripts separately; redaction and sanitisation are deliberately two different tools because they solve different leak vectors.

Is it worth it

Ten minutes of Docker setup buys permanent independence from an entire category of web tools that were never a great idea to trust with sensitive documents in the first place. The operations Stirling covers are things almost everyone needs occasionally rather than constantly, which is exactly the profile of tool that’s easy to keep putting off self-hosting because “I’ll just use the free site this once.” I’d rather have it sitting there, updated and ready, than make that judgement call under time pressure with a document I actually care about open in another tab. If you already run something like Paperless-ngx for long-term document storage, Stirling is the natural companion for the one-off manipulation that happens before a document is ready to file away.