Deploy and Host Stirling PDF on Railway

Stirling PDF is the most-starred open-source PDF toolkit on GitHub — 50+ operations (merge, split, convert, OCR, sign, compress, redact, and more) in a clean web UI and a full REST API. It's a private, self-hosted alternative to Adobe Acrobat and SmallPDF where every file is processed on your own server and deleted immediately after. This template deploys it with login enabled and both configuration and OCR language data persisted — so multi-language OCR survives redeploys, which most templates get wrong.

What This Template Deploys

Service	Purpose
Stirling PDF	The full PDF toolkit, web UI, and REST API on port `8080` (`latest-fat` image with security)

A single service. Persistent volumes hold the /configs directory (user database, settings, AOT cache) and the Tesseract tessdata directory (OCR language packs) — so both user accounts and downloaded OCR languages survive redeploys.

About Hosting

Stirling PDF wraps LibreOffice, Tesseract, and qpdf into one interface, and hosting it on Railway has three specifics that determine whether it works.

Use the latest-fat image, not latest. The standard image ships without the security JARs, so login silently doesn't work — the app loads straight to the tools with no authentication, no matter how you set the login variables. The -fat image includes the security components and enables DISABLE_ADDITIONAL_FEATURES=false to take effect. This is the single most common Stirling PDF deployment mistake, and this template uses the correct image.

First boot takes about 90 seconds. Spring Boot warms its bean graph and LibreOffice's conversion pool initializes on startup. Railway's default healthcheck would flag the service unhealthy before that completes, so this template sets a generous healthcheck window — a slow first boot is normal, not a failure.

OCR languages need a persisted tessdata volume — and most templates skip it. Extra Tesseract language packs live in /usr/share/tessdata, downloaded on first use. If that directory isn't on a volume, every redeploy wipes non-English OCR support. This template persists it, so a legal or healthcare team running French, Spanish, or German OCR keeps it across redeploys — the difference that matters for anyone using OCR beyond English.

Files themselves are never stored — Stirling processes each in memory and deletes it immediately, so nothing sensitive lingers on the server.

Typical cost: ~$5–10/month on Railway. Stirling PDF is MIT-licensed; Adobe Acrobat Pro runs about $20/month per seat for less privacy.

How It Compares

	Stirling PDF (self-hosted)	Adobe Acrobat	SmallPDF	iLovePDF
Cost model	Flat ~$5–10/mo infra	~$20/user/month	Per user/month	Per user/month
File privacy	Your server only	Adobe cloud	Their servers	Their servers
Operations	50+	Extensive	Common set	Common set
REST API	Yes	Limited	Paid tier	Paid tier
OCR	Yes, multi-language	Yes	Yes	Yes
Self-hostable	Yes	No	No	No

Adobe and the cloud tools are more polished and widely recognized, but every file passes through their servers. Stirling PDF covers the operations most people actually use, exposes a full API, and keeps every document on infrastructure you own — the deciding factor for legal, healthcare, and finance teams.

Deploy in Under 5 Minutes

Click Deploy on Railway — Stirling PDF builds automatically (first boot ~90 seconds; this is normal)
Set SECURITY_INITIALLOGIN_USERNAME and SECURITY_INITIALLOGIN_PASSWORD to your own values before first boot
Confirm volumes are mounted at /configs and the tessdata path
Open your Railway domain and log in with the credentials you set
Use the web UI, or call the REST API with the X-API-Key header for automation

Don't leave the default admin / stirling credentials on a public instance — they're widely known.

Common Use Cases

Private Adobe Acrobat alternative — merge, split, compress, convert, and edit PDFs without files leaving your server
Multi-language OCR — make scanned documents searchable in English and any Tesseract language, with the packs persisted across redeploys
Document automation via API — call 50+ PDF operations from scripts, n8n, or backend workflows using the REST API and an API key
Sign and redact — add signatures and permanently redact sensitive content before sharing documents

Configuration

Variable	Required	Description
`DISABLE_ADDITIONAL_FEATURES`	Pre-set	`false` — required for login and security features (needs the `-fat` image)
`DOCKER_ENABLE_SECURITY`	Pre-set	`true` — enables the security components
`SECURITY_ENABLELOGIN`	Pre-set	`true` — turns on the login screen
`SECURITY_INITIALLOGIN_USERNAME`	Required	Admin username — set before first boot
`SECURITY_INITIALLOGIN_PASSWORD`	Required	Admin password — set a strong value, don't leave the default
`SECURITY_CUSTOMGLOBALAPIKEY`	Recommended	API key for REST access — the template seeds one
`LANGS`	Optional	OCR/UI languages, e.g. `en_GB,fr_FR,de_DE`
`SYSTEM_DEFAULTLOCALE`	Optional	Default UI language, e.g. `en-US`
`SYSTEM_MAXFILESIZE`	Optional	Maximum upload size in MB

Set a strong admin password before first boot. With login enabled and no credentials set, Stirling PDF defaults to admin / stirling, which is widely known. Set your own username and password, or change them immediately on first login.

Both volumes matter. /configs holds the user database and settings; the tessdata volume holds OCR language packs. Without the first, user accounts reset on redeploy; without the second, non-English OCR languages are lost.

Dependencies for Stirling PDF Hosting

Railway account — Hobby plan (~$5–10/month) runs the toolkit
Persistent volumes for /configs and OCR tessdata (included)
2 GB RAM recommended; conversion and OCR are memory-intensive
Optional: additional Tesseract .traineddata files for more OCR languages

Deployment Dependencies

Implementation Details

The template runs stirlingtools/stirling-pdf:latest-fat on port 8080. The -fat variant bundles the security JARs, so DISABLE_ADDITIONAL_FEATURES=false, DOCKER_ENABLE_SECURITY=true, and SECURITY_ENABLELOGIN=true actually enable authentication — with the standard latest image these settings have no effect and the app loads unprotected.

Two volumes are mounted. The /configs directory holds the embedded H2 user database, settings, and the AOT cache, so accounts and configuration persist. The Tesseract tessdata directory holds OCR language packs, otherwise downloaded to ephemeral storage and lost on redeploy — persisting it keeps multi-language OCR working, and it's the piece most Stirling PDF templates omit.

Because Spring Boot and LibreOffice's unoserver take about 90 seconds to initialize on first boot, the healthcheck window is set generously so Railway doesn't kill the service mid-startup. The REST API is available at /swagger-ui/index.html, authenticated with the X-API-Key header against SECURITY_CUSTOMGLOBALAPIKEY.

Frequently Asked Questions

Why doesn't the login screen appear? Almost always because the image is latest instead of latest-fat. The standard image lacks the security JARs, so login can't work regardless of the variables. This template uses latest-fat, which includes them.

Do OCR languages survive a redeploy? Yes, because this template persists the tessdata volume. Many templates don't, so their non-English OCR packs vanish on every redeploy. Add language codes to LANGS and drop .traineddata files into the volume.

Why does it take 90 seconds to start? Spring Boot and the embedded LibreOffice conversion pool initialize on first boot. Railway's healthcheck is configured to wait, so a slow first start is expected, not a failure.

Do my user accounts persist? Yes. The /configs volume holds the user database and settings, so accounts survive redeploys. Without that volume you'd log in with seed credentials every time.

How do I use the REST API? Set SECURITY_CUSTOMGLOBALAPIKEY (the template seeds one) and call any endpoint with the X-API-Key header. The full reference is at /swagger-ui/index.html on your deployment.

Are my files stored anywhere? No. Stirling PDF processes each file in memory and deletes it immediately after the operation. Nothing is stored, logged, or sent to a third party.

Can it replace Adobe Acrobat? For most common operations — merge, split, convert, OCR, sign, compress, redact — yes, with full privacy and a REST API. Some of Acrobat's most advanced editing features have no equivalent.

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 get a private, full-featured PDF toolkit with the pitfalls solved — the latest-fat image so login works, a generous healthcheck for the slow first boot, and both configuration and OCR language data persisted so nothing resets on redeploy. 50+ PDF operations and a REST API, with every document on infrastructure you own.