Deploy PDF Toolkit (Stirling-PDF) | (Just Updated) Server-Side OCR, Convert, Merge — No Default Admin Login

Deploy and Host Stirling-PDF on Railway

Stirling-PDF is a self-hosted PDF toolkit: OCR scanned documents, convert Office files and images to PDF, merge, split, rotate, compress, sign, redact, add or remove passwords, and run the same 50+ operations over a documented REST API. Unlike browser-only PDF apps, the heavy work (Tesseract OCR, LibreOffice conversion, Ghostscript compression) runs on the server, so it also works as an automation backend for scripts, n8n and agents.

About Hosting Stirling-PDF

This template deploys the official stirlingtools/stirling-pdf:2.14.3-fat image — the variant that ships Tesseract, LibreOffice, Ghostscript, qpdf, ImageMagick and Calibre, so OCR and Office conversion work on the first request with nothing to install.

Two things are done differently here, and both were measured against the other Stirling-PDF listings on Railway:

1. The admin account is seeded from a generated secret. Stirling-PDF creates a admin / stirling account whenever SECURITY_INITIALLOGIN_PASSWORD is empty — and it does that in the fat image even with DOCKER_ENABLE_SECURITY=false, because the security profile is always active in that jar. On a public Railway URL that means anyone can log in with the documented default and take the instance over. This template generates the password per deploy and refuses to boot if it is blank.
2. Everything stateful lands on one volume. Railway allows a single mount per service, while Stirling-PDF writes to five paths: /configs (settings plus the H2 user database), /storage (server-side file storage), /customFiles (branding overrides), /pipeline (automation configs) and /logs. The start command relocates all five onto /data and repairs ownership, because Railway mounts volumes as uid 0 while the app runs as uid 1000.

No JVM heap flag is set on purpose: the image's own init script reads the container's cgroup memory limit and applies -XX:MaxRAMPercentage=50, so a fixed -Xmx only caps the heap below what the plan already allows.

Common Use Cases

• A private PDF workbench for a team that cannot upload contracts or scans to a cloud service.
• An OCR and conversion backend called over the REST API from scripts, n8n or an AI agent.
• A self-hosted replacement for paid PDF suites, with per-user logins and no page limits.

Dependencies for Stirling-PDF Hosting

Deployment Dependencies

Implementation Details

Variables the deploy form asks for — both are pre-filled with generated secrets, so the form can be submitted as-is:

Everything else — login enforcement, upload limit, locale, forwarded-header strategy, analytics and survey opt-outs — is set by the start command rather than published as a blank field for you to fill in.

After deploying: open the generated URL, log in as admin with the value of SECURITY_INITIALLOGIN_PASSWORD from the service variables, and change it in the account settings. API calls use the same instance:

curl -H "X-API-KEY: $SECURITY_CUSTOMGLOBALAPIKEY" \
  -F "fileInput=@scan.pdf" -F "ocrType=skip-text" -F "languages=eng" \
  https://your-app.up.railway.app/api/v1/misc/ocr-pdf -o ocr.pdf

Additional OCR languages can be added by dropping .traineddata files into the Tesseract data directory, and extra Stirling settings can be edited in /data/configs/settings.yml, which survives redeploys.

Why Deploy Stirling-PDF on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Stirling-PDF on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.