How to Self-Host Stirling PDF in 2026: Uploads, OCR and Login Security

There are two versions of “running Stirling PDF”: a container exists, or the service completes its real job. Only the second matters. Here the proof is to merge two PDFs, OCR a scanned page, compress the result and verify upload and download behavior through the public proxy.

Stirling PDF serves this purpose: web interface and API for common PDF operations. The deployment has to preserve the pieces behind that behavior; a port, a volume and a certificate are inputs, not the result.

Container settings worth reviewing

The first container should be easy to delete and recreate. Keep data off the writable layer, bind port 8080 only where the proxy can reach it and pass configuration at runtime.

docker run -d \
  --name stirling-pdf \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v stirling-pdf-data:/configs \
  -e SECURITY_ENABLELOGIN=true \
  stirlingtools/stirling-pdf:latest

Pin the image after the initial test. Read the earliest startup error rather than the final restart message, verify each mount with docker inspect, and follow logs while you merge two PDFs, OCR a scanned page, compress the result and verify upload and download behavior through the public proxy. That sequence distinguishes a bad image command from a dependency or permission problem.

Define success for Stirling PDF first

Separate four concerns for Stirling PDF: ingress, the listener on 8080, durable state and supporting services or local capacity. The local runtime requirement is optional OCR language data and enough temporary disk for large jobs. Record it beside the image and port so a replacement host receives the same local capability.

Run the known-good transaction — merge two PDFs, OCR a scanned page, compress the result and verify upload and download behavior through the public proxy — before calling that separation complete. Measure temporary disk, OCR language packs, JVM memory and simultaneous conversion jobs and keep the result with the deployment record. It provides both an acceptance criterion and the first capacity baseline.

Lock down Stirling PDF after bootstrap

The application-specific security risk is leaving security disabled on a public document-processing service. The operational answer is to enable login for an internet-facing instance and avoid retaining uploaded documents longer than the job requires. Finish bootstrap through a restricted route and remove temporary setup access immediately afterward.

SECURITY_ENABLELOGIN controls behavior rather than confidentiality; validate its type and value, and store genuine Stirling PDF credentials separately. Give the Stirling PDF process only its documented mounts and dependency routes; avoid host root and Docker socket access. Log failed authentication and configuration errors, but redact tokens, connection strings and user content.

Give Stirling PDF one canonical address

The browser, API client and Stirling PDF must agree on one origin. To make that true, set the public HTTPS origin and proxy upload limits. Preserve the original host and protocol while keeping port 8080 unavailable as a competing public address.

The site-down troubleshooting guide helps distinguish an unreachable route from a responding application. That distinction matters here: uploads exceed the proxy limit or the container cannot write temporary files. Only the former is fixed by ingress changes; the latter needs Stirling PDF logs, state or workload inspection.

Separate replaceable containers from lasting data

The durable recovery set is configuration, custom files and any OCR data you deliberately installed. Mount /configs before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. A volume protects data from container replacement, but not from host loss, accidental deletion or application-level corruption.

Take backups that understand the data source: use logical dumps for live databases when required and copy files only from a consistent state. Keep one encrypted copy away from the Stirling PDF host. The acceptance criterion for a restore is specific — configuration and OCR assets return and a fixed test document produces an acceptable, readable result. The restore-tested backup guide explains why job success alone is insufficient.

Evidence to collect before Stirling PDF goes live

For Stirling PDF, define a known-good transaction before launch: merge two PDFs, OCR a scanned page, compress the result and verify upload and download behavior through the public proxy. Put its prerequisites, expected response and cleanup steps in version control without secret values. Pin the image used to establish that reference.

Use the transaction to validate a replacement and an independent restore. The restored service is acceptable only when configuration and OCR assets return and a fixed test document produces an acceptable, readable result. At the same time, observe temporary disk, OCR language packs, JVM memory and simultaneous conversion jobs and turn the slowest or most constrained part into a service-level alert.

The gate also needs a negative case: submit harmless input near the resource or format limit associated with this boundary: uploads exceed the proxy limit or the container cannot write temporary files. Confirm that Stirling PDF produces an actionable error while preserving data, restore the valid condition and repeat the known-good transaction. Keeping both results prevents a superficial health endpoint from becoming the only production evidence.

Operate Stirling PDF around its real bottleneck

Observe the work Stirling PDF performs: temporary disk, OCR language packs, JVM memory and simultaneous conversion jobs. Set limits with headroom for that work and avoid a liveness probe that competes with it. The operator check should still attempt to merge two PDFs, OCR a scanned page, compress the result and verify upload and download behavior through the public proxy on a schedule.

For updates, remember that installed OCR data, custom configuration and security settings should be compared before an image upgrade. Deploy the candidate against a recovered copy and repeat the known test. If uploads exceed the proxy limit or the container cannot write temporary files, use runtime logs and the actual network request to find which assumption changed.

Deploy Stirling PDF on Dockup without losing its boundaries

Dockup removes manual reverse-proxy and lifecycle work around Stirling PDF. The service receives a stable HTTPS route to 8080, injected configuration and persistent storage during replacements. An attached customer server follows the same model as Dockup-hosted compute.

After launch, satisfy the application contract: set the public HTTPS origin and proxy upload limits, confirm the local requirement — optional OCR language data and enough temporary disk for large jobs and run this proof: merge two PDFs, OCR a scanned page, compress the result and verify upload and download behavior through the public proxy. This keeps the one-click experience useful without flattening the details that make Stirling PDF recoverable and secure.

Frequently asked questions

What does Stirling PDF need for a production deployment?

Route the Stirling PDF container on port 8080 through one HTTPS origin. The local runtime requirement is optional OCR language data and enough temporary disk for large jobs. Do not call Stirling PDF ready until you can merge two PDFs, OCR a scanned page, compress the result and verify upload and download behavior through the public proxy.

Which Stirling PDF data belongs in a backup?

Persist /configs and include configuration, custom files and any OCR data you deliberately installed in the same recovery manifest. A clean Stirling PDF restore passes only when configuration and OCR assets return and a fixed test document produces an acceptable, readable result.

Does Stirling PDF require HTTPS behind a reverse proxy?

Use HTTPS for the public Stirling PDF origin and keep port 8080 on the internal route. Apply the Stirling PDF setting correctly: set the public HTTPS origin and proxy upload limits. For Stirling PDF, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a Stirling PDF upgrade be tested?

Restore current Stirling PDF state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because installed OCR data, custom configuration and security settings should be compared before an image upgrade. Keep the previous Stirling PDF image until its data-migration and rollback boundary are understood.