# Stirling PDF: Self-Hosted PDF Editing with Docker and a Private API

> Stirling PDF is an open-core Java application that runs PDF editing as a web UI, desktop client or self-hosted server. The README gives a one-line Docker start, but the documentation is where the deployment and licence details live.

**Stirling-Tools/Stirling-PDF** — Stirling PDF is an open-source PDF platform with 50+ tools to edit, merge, sign, redact, convert, and OCR files, self-hosted so documents never leave your servers.

- Repository: https://github.com/Stirling-Tools/Stirling-PDF
- Website: https://stirling.com
- Stars: 93,263 · Forks: 10,003
- Language: Java
- License: not declared
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/stirling-tools-stirling-pdf

## What Stirling PDF solves, and who it is built for

The README frames the problem directly: edit, sign, redact, convert and automate PDFs "without sending documents to external services." That is the whole pitch. If your documents contain contracts, medical records, internal financials or anything else that cannot leave your network, the usual answer is a desktop PDF suite installed on each machine, or a cloud service with a data processing agreement attached. Stirling PDF offers a third shape: one server you run, reachable from a browser, with a REST API on the same surface.

The audience follows from that. It is for teams that already run Docker or Kubernetes and are comfortable owning a service. It is also for individual engineers who want a private endpoint for scripted PDF work rather than a GUI. The README lists desktop client, browser UI and self-hosted server as three deployment shapes, and it advertises SSO, auditing and on-prem deployment as enterprise features. The 40+ UI languages matter most in organisations where the people doing the PDF work are not the people running the server.

Where it fits less well is the single user who edits a PDF twice a month. A local desktop application has no server to patch and no port to expose. Stirling PDF's value is proportional to how many people and how much automation sit behind it.

## How the pieces fit: Java backend, browser frontend, REST API

The repository layout tells you more than the README does. There is an app/ directory and an engine/ directory at the top level alongside frontend/, build.gradle, settings.gradle and gradle.properties. That is a Gradle multi-module Java build with a separated frontend, which matches the README's description of a browser UI backed by a processing API. The API documentation is published separately, and the README states that REST APIs are available for nearly all tools.

That last word matters. "Nearly all" is a hedge, and the README does not enumerate which tools are missing from the API. If you plan to drive Stirling PDF entirely from scripts, the API reference is the place to confirm coverage per tool rather than assuming the UI and the API expose the same set.

The README also describes no-code pipelines configured in the UI, with APIs for processing large volumes of PDFs. So there are two automation paths: a visual pipeline builder and direct API calls. Which one suits you depends on whether the pipeline steps you need are exposed as pipeline nodes. The repository carries documentation files such as ADDING_TOOLS.md and HowToUseOCR.md, which suggests the project expects people to extend the tool set rather than only consume it.

One structural detail worth noting: DATABASE.md exists at the top level. A PDF tool that needs a database is doing more than stateless conversion. The v2.14.2 release notes describe a hotfix "for certain postgres environments," which confirms PostgreSQL is a supported backend and that the project has had environment-specific database issues within the last two releases.

## Installing Stirling PDF with Docker and running a first job

The README's Quick Start is a single command. It pulls the image from the project's own registry host and maps port 8080.

```bash
docker run -p 8080:8080 docker.stirlingpdf.com/stirlingtools/stirling-pdf
```

After the container starts, the README says to open http://localhost:8080. You should see the Stirling PDF web interface with its tool list. The README does not give a volume mount, an environment variable or a tag in this example, so this command produces a container whose state does not survive removal. For anything beyond a trial, the documentation guide linked from the README is where persistent storage and configuration are covered.

The README also points at a Docker Hub image at stirlingtools/stirling-pdf, so there are two image sources in play. The Quick Start uses the docker.stirlingpdf.com host while the badge links to Docker Hub. Pick one deliberately rather than mixing them across environments.

For a Compose-based deployment, the README does not provide a Compose file. The installation options it defers to are in the documentation, and it names desktop and Kubernetes as supported alongside the server. If you are targeting a NAS such as a Synology device, the README says nothing specific; treat that as a Docker deployment and check the documentation guide for anything the single command omits.

For contributors rather than users, the README gives a different entry point. The project uses Task as its command runner, and `task dev` is documented as the way to start the editor locally. `task` alone lists the common commands.

## Open-core licensing is the constraint to read before you deploy

The README's licence section is one sentence: "Stirling PDF is open-core. See LICENSE for details." That is the most important line for anyone evaluating adoption, and it is also the least informative. Open-core means some functionality is open and some is not, and the README does not say where the line falls.

The README points to a Server Plan and Enterprise page under Paid-Offerings in the documentation. It lists SSO, auditing and flexible on-prem deployments under an "Enterprise-grade" heading. Read together, those two facts suggest that at least some of the enterprise feature set is tied to a paid offering, but the README never states explicitly which features are free and which are not. Do not infer it from the marketing headings. Open LICENSE and the Paid-Offerings page and map them against your own requirements list.

There is a practical consequence for upgrades. If a feature you depend on sits on the paid side, a future version is not something you can simply rebuild from source. The repository is not archived and the last push was on 2026-08-06, so the project is moving, but movement in an open-core project can shift the boundary. The v2.14.1 release notes mention a new third-party licence page, which at least indicates the project takes licence disclosure seriously enough to surface it in the product.

This is not legal advice. If your organisation has a policy on open-core dependencies, the LICENSE file and the Paid-Offerings documentation are the two documents that policy needs to see.

## Where Stirling PDF is the wrong tool

The first limitation is operational, not functional. A self-hosted PDF service is a network service. It parses untrusted files, which is exactly the workload class where parser vulnerabilities matter. The repository carries a SECURITY.md and a .gitleaksignore, and there is a Scorecard badge in the README, so the project has some security process around it. None of that removes the obligation on you to decide who can reach port 8080. An instance exposed to the open internet with no authentication in front of it is a different risk from one behind a VPN, and the README's Quick Start command does not address access control at all.

The second limitation is the API coverage gap already noted. If your workflow depends on a specific tool and that tool is not exposed through the REST API, you are either driving the UI by hand or writing against an interface the README does not promise. Check the API reference before you design around it.

The third is version cadence. The three most recent releases listed are v2.14.3, v2.14.2 and v2.14.1, and v2.14.2 is described as a hotfix for certain PostgreSQL environments. Frequent patch releases are normal for a project this size, but a database-specific hotfix two releases back means you should test upgrades against your own database rather than assuming they are drop-in.

Finally, consider whether you need a server at all. For occasional single-document editing on one machine, a desktop application has no deployment surface, no upgrade window and no port. Stirling PDF's desktop client exists, but the README treats it as one of three deployment shapes rather than the default.

## Stirling PDF compared with Bento PDF and the desktop route

Bento PDF is the comparison people search for, and the difference in approach is architectural rather than a feature checklist. Stirling PDF is a server-side application: the Java backend does the PDF processing, the browser is a client, and the same operations are reachable over HTTP. That is what makes SSO, auditing, shared pipelines and API automation possible, and it is also what makes you responsible for running and securing a service.

A client-side PDF tool takes the opposite position. Processing happens in the browser or on the local machine, there is no backend to deploy, and the document never travels to your server because there is no your server. The trade-off is that anything requiring shared state, central policy or programmatic access across a fleet is either impossible or has to be built around the tool.

So the choice is not which tool has more features. It is whether your PDF work is a shared service or a personal task. If several people need the same operations with the same audit trail, and scripts need to call those operations, a server-side design is the only one that fits, and Stirling PDF is one of the few in that category that you can host yourself. If one person needs to fill in a form, the server is overhead you will pay for every month in patching and monitoring.

The README's own framing supports this reading: it lists desktop client, browser UI and self-hosted server as three ways to run the same platform, and describes private APIs as the thing the self-hosted path buys you.

## Maintenance, upgrades and what to watch between releases

Stirling PDF is not archived, and the last push was on 2026-08-06, which is recent enough that the repository is clearly receiving changes. The release list shows three versions in roughly a month, with the middle one a targeted hotfix. That is a project that ships often, and it means your upgrade cadence is a real decision rather than an annual event.

The cost of that cadence is testing. A hotfix scoped to "certain postgres environments" tells you the project supports more than one database configuration and that behaviour differs between them. If you run PostgreSQL, your upgrade test needs to cover it. If you run the default embedded storage, your test is different. The README does not document rollback, so plan how you would return to the previous image tag before you need to.

On licence implications, the README's single sentence about open-core is the whole of what the repository states up front. The LICENSE file and the Paid-Offerings documentation are the sources for the actual terms, and the v2.14.1 release notes mention a new third-party licence page in the product, which is a reasonable place to see what dependencies ship inside the image. Nothing here is legal advice; if your organisation gates open-core dependencies, those documents are the inputs to that gate.

One more maintenance note from the README: the project uses Task as a unified command runner for build, dev and test. If you build from source rather than pulling an image, that is the toolchain you are signing up to, and `task` with no arguments lists the common commands.

## Conclusion

Adopt Stirling PDF if your PDF work has to stay on infrastructure you control and you want a browser UI plus REST endpoints for the same operations; the README's Docker command is the shortest path to a running instance. Do not adopt it expecting a permissively licensed codebase, because the README states the project is open-core and points to LICENSE for the split. Before you commit, verify three things: which tools your use case actually needs and whether they sit on the open or paid side of that split, whether the SSO and auditing features you want are part of the free server or the Server Plan, and whether your deployment target is covered by the documented installation options rather than by the single Docker example in the README.

## FAQ

### Is Stirling PDF free?

The README describes the project as open-core and points to the LICENSE file for details, and it links to a Server Plan and Enterprise page under Paid-Offerings in the documentation. That means some functionality is open and some is tied to a paid offering, but the README does not state which features fall on which side. Check the LICENSE file and the Paid-Offerings page before assuming a specific tool is free.

### Is Stirling PDF open source?

The README says "Stirling PDF is open-core" and directs readers to LICENSE for details, so the source is available but the licence is not a single permissive grant across the whole product. The README does not spell out the split. The LICENSE file is the authoritative document.

### Is Stirling PDF safe to use?

The README's stated design goal is to let you edit PDFs "without sending documents to external services," which means a self-hosted instance keeps documents on your own infrastructure. The README does not describe authentication on the Quick Start command, so who can reach port 8080 is your decision. The repository includes a SECURITY.md and a Scorecard badge, which indicate some security process, but the README does not document a threat model.

### How do I install Stirling PDF with Docker?

The README's Quick Start runs a single command that pulls the image and maps port 8080, then tells you to open http://localhost:8080. That example includes no volume mount or environment variable, so it is a trial setup rather than a persistent deployment. The README defers full installation options, including desktop and Kubernetes, to the documentation guide.

### What is Stirling PDF?

It is an open-core PDF platform that runs as a desktop client, a browser UI or a self-hosted server with a private API. The README lists more than 50 PDF tools covering editing, merging, splitting, signing, redaction, conversion, OCR and compression, plus a REST API for nearly all tools and a UI available in 40+ languages.

### How do I install Stirling PDF on Windows?

The README does not give Windows-specific installation steps. It names desktop and Kubernetes as supported alongside the Docker server and points to the documentation guide for full installation options, so that guide is where to look. The repository does contain WINDOWS_SIGNING.md and launch4jConfig.xml, which relate to building a Windows executable rather than to end-user installation.

## Sources

- [Official documentation](https://stirling.com)
- [Official README](https://github.com/Stirling-Tools/Stirling-PDF#readme)
- [Project repository](https://github.com/Stirling-Tools/Stirling-PDF)
- [Release notes](https://github.com/Stirling-Tools/Stirling-PDF/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stirling-tools-stirling-pdf