Stirling-PDF does all the fiddly things people do to PDFs, like merging, splitting, compressing, converting and making scans searchable, in your browser, without uploading them to a stranger's website.
On this page
Good to know before you install
OCR arrives with English, German, French, Portuguese and Simplified Chinese only; other languages need their Tesseract .traineddata files dropped into the app's data/tessdata folder.
At a glance#
- What it is
- PDF Toolkit Productivity
- Where it opens
- Web Interface
On its own port at
http://your-server:port, orpdf.your-domainonce you have a domain - Updates
- Automatic A backup is taken first, and it rolls back if the update fails
- Backups
- Included Part of the daily backup when that's switched on
- Copies
- As many as you like Run several copies, each with its own data
What it's good for#
Sooner or later everyone needs to join two PDFs, take a page out of one, shrink a scan small enough to email, or turn a photo into a PDF. The usual answer is a free website that wants your documents, which isn't a great idea for a bank statement or a tenancy agreement. Stirling-PDF gives you the same tools, dozens of them, on your own server.
Some of the handiest:
- Merge, split, rotate and rearrange pages.
- Compress a big scan down to something you can email.
- Convert to and from PDF: images, Office documents, web pages.
- OCR, which reads the text in a scan so you can search it and copy from it.
- Sign, add a watermark, or redact parts of a page.
Using it#
Open it with the Web Interface button, pick a tool (the search box at the top finds one quickly), drop your file in and download the result. Files up to 100 MB are accepted; if you work with long scanned books, raise Maximum Upload Size (see Settings below), and Interface Language sets the language it starts in. The server only holds your file while it works on it; it doesn't keep a library of your documents.
There's no sign-in to start with. Anyone who can reach it can use it, which is fine at home and why LibrePortal leaves its login off; see below if you want one.
Turning the login on#
If Stirling-PDF is public, or you'd like each person to have their own settings, switch Require Login on (it's in the config file too). Stirling-PDF then makes its first admin the first time it starts with login on. Upstream's own first admin is the published admin / stirling, which anyone could guess, so LibrePortal hands it a username of admin and a generated password instead. That password is in the Login Details; press Welcome on the app's page to see it.
Once you're in as the admin, you can add accounts for other people in Stirling-PDF's own settings.
Installed with 0.4.6 or earlier?
An older install was set up without that generated first login, and the update doesn't add it by itself. Switch Require Login on from the Config tab and press Update Configuration: that sets Stirling-PDF up again from LibrePortal's current version of it, so the first admin gets the generated password. Switched on any other way, such as changing the setting from the command line and restarting, an older install still makes upstream's admin / stirling. If yours already has that login, sign in and change its password straight away.
Changing the password later
LibrePortal's password is only used to create that first admin. Once the account exists, change its password inside Stirling-PDF; changing LibrePortal's copy afterwards doesn't reach it, and the Login Details will then show the old one.
OCR in other languages#
OCR arrives knowing English, German, French, Portuguese and Simplified Chinese. For another language, Stirling-PDF needs that language's Tesseract data file (a .traineddata file, from the Tesseract project's tessdata downloads) in the app's data/tessdata folder on the server. Once it's there, the language appears in the OCR tool.
To check: say how to put a tessdata file into the app's data/tessdata folder without hand-editing the app's files (and whether Stirling-PDF needs a restart to see it)
Good to know#
- Updates are automatic. Stirling-PDF moves quickly and adds tools often.
- Backups include its settings, accounts and any custom files, not the PDFs you've worked on, which it doesn't keep.
- More than one copy is possible, each with its own settings.
Addresses and ports#
Stirling-PDF has one port. LibrePortal picks a free port number for each when you install, so yours will differ from anyone else's. The Config tab's Network section shows them, and the app's Open button uses the right one. "Anyone" means it's reachable from wherever your server is reachable; you can make it private later.
| What it is | Who can reach it | With a domain |
|---|---|---|
| Web Interface | Anyone | pdf.your-domain |
Settings#
In its config file#
Stirling-PDF's own settings aren't on the Config tab yet. They live in the app's config file, described here so you know they exist. How to change them.
| Setting | What it does | Starts as |
|---|---|---|
NameCFG_STIRLINGPDF_DISPLAY_NAME |
What this app is called on your dashboards. Leave empty to use its usual name | Empty |
Show on the LibrePortal DashboardCFG_STIRLINGPDF_SHOW_ON_DASHBOARD |
Whether this app gets a shortcut on the front page of the LibrePortal WebUI, separate from any Dashy dashboard Choices: true, false |
true |
Require LoginCFG_STIRLINGPDF_LOGIN_ENABLED |
Whether Stirling-PDF asks for one of its own accounts before letting anyone use it Choices: true, false |
false |
Interface LanguageCFG_STIRLINGPDF_LOCALE |
The language the app starts in, as a locale code such as en-GB, de-DE or fr-FR | en-GB |
Maximum Upload SizeCFG_STIRLINGPDF_MAX_FILE_SIZE |
The biggest file the app will accept, in MB | 100 |
Usage trackingCFG_STIRLINGPDF_TELEMETRY |
Whether Stirling PDF may send usage analytics out (analytics, PostHog and the Scarf pixel). Choices: true, false |
false |
Update noticeCFG_STIRLINGPDF_UPDATE_CHECK |
Whether Stirling PDF may ask its servers about new versions and show a banner. Choices: true, false |
false |
Detailed logsCFG_STIRLINGPDF_VERBOSE_LOGS |
Whether Stirling PDF writes its normal, chattier logs, including who connected, instead of only warnings and errors. Choices: true, false |
false |
Debug logging for 24 hoursCFG_STIRLINGPDF_DEBUG_LOGS |
Turn on to see everything Stirling PDF is doing while you look for a problem; it turns itself off after 24 hours. Choices: true, false |
false |
Works with#
These are the other apps Stirling-PDF knows how to work with. Once it's installed, its page shows the same list with whether each one is connected. How this works.
- Grafana: Shows dashboards for the apps that have one. works with every app
- Prometheus: Collects metrics from the apps that can export them. works with every app
- Uptime Kuma: Watches your apps and shows when one goes down. works with every app
Privacy and security#
All clear Stirling PDF edits PDFs on your server so your files never go to a website. LibrePortal switches off its usage tracking and update notice; the PDFs stay local.
What leaves this server#
- Tools that fetch web pages (such as URL to PDF) contact the sites you give them
What LibrePortal turns off#
- Detailed logs and per-request access logging (switchable in Config)
- Analytics, PostHog and Scarf tracking (switchable in Config)
- Update notice (switchable in Config)
Licence: MIT core plus proprietary directories (app/proprietary, app/saas, engine) under separate licences - open core. Audited: 21 October 2026. See the privacy of every app and the Promise.
Sources#
Under the hood#
- It runs this image:
stirlingtools/stirling-pdf:3.0.2@sha256:c195925341aa35ee5932d9c225edef48a92e46a1280963180d79619cb5f29e6e. - It can sit behind Authelia's sign-in once Authelia is installed.
- Its own project and documentation: github.com/Stirling-Tools/Stirling-PDF
Ports, settings, tools and connections on this page are read from LibrePortal v0.10.97's app catalogue each time the guide is built.