Why Self-Hosted PDF Editing Makes Sense
Stirling PDF is an open-source, self-hosted web application that puts a full suite of PDF tools under your control – no cloud uploads, no subscription fees, no file size limits set by a third party.
What Stirling PDF Actually Does
Before diving into the setup, it helps to understand what you are actually getting. Stirling PDF is not just a viewer or a simple merger. It covers splitting, merging, rotating, compressing, converting to and from other formats, adding watermarks, extracting images, OCR via Tesseract, and even signing documents. The full feature list runs to well over 30 tools accessible through a clean browser-based interface. That makes it comparable to desktop software like Adobe Acrobat without the annual cost or the requirement that your files ever leave your server.
The project runs as a Docker container, which is the recommended and by far the simplest deployment path. If you already have Docker and Docker Compose installed on a Linux machine, a Raspberry Pi, or a home server running something like Proxmox or Unraid, you are most of the way there. The container pulls in all dependencies, including optional ones for OCR language packs, so there is nothing to compile or configure at the system level.
Stirling PDF stores no data between sessions by default. Files are processed in memory and discarded once you download the result. That is the whole point for many users – sensitive documents like contracts, tax forms, or medical records never have to touch a commercial server. If you are already running something like a self-hosted household management stack, adding Stirling PDF to the same Docker Compose environment is minimal overhead.
There are two Docker image variants: the standard image and the “fat” image, which bundles Tesseract OCR language packs and LibreOffice for document conversion. If you need to run OCR on scanned PDFs or convert Word documents to PDF, use the fat image. Otherwise the standard image is leaner and faster to pull.
Setting Up Stirling PDF with Docker Compose
Create a directory for your Stirling PDF setup – something like /opt/stirling-pdf on Linux – then create a docker-compose.yml file inside it. The basic configuration looks like this:
- image: Use frooodle/s-pdf:latest for the standard image or frooodle/s-pdf:latest-fat for the full OCR and conversion build.
- ports: Map host port 8080 to container port 8080, or change the host-side port to whatever fits your network.
- volumes: Mount a local directory to /configs inside the container if you want to persist settings like custom app name, default language, or login credentials. A second mount to /customFiles is optional but useful for custom fonts and templates.
- environment: Set DOCKER_ENABLE_SECURITY=false to skip login enforcement on a trusted local network, or set it to true and define an admin username and password if you are exposing the service beyond your LAN.
- restart: Set to unless-stopped so the container comes back up after a reboot without manual intervention.
Once the file is saved, run docker compose up -d from that directory. Docker will pull the image on first run – the fat image is around 2.5 GB, so allow time for the download on slower connections. After the container starts, open a browser and navigate to http://your-server-ip:8080. The Stirling PDF interface should appear immediately, no further configuration required for basic use.
If you want to enable authentication – which you absolutely should if this service is reachable outside your home network – set DOCKER_ENABLE_SECURITY=true and add the environment variables SECURITY_ENABLELOGIN=true, along with a default username and password. On first login you will be prompted to change that password. Stirling PDF also supports single sign-on via OAuth2 if you run an identity provider like Authentik or Keycloak on your network, which is worth setting up if you already have that infrastructure.
Putting Stirling PDF behind a reverse proxy like Nginx Proxy Manager or Caddy is the standard approach for anyone who wants HTTPS. Point your proxy to the container’s internal IP and port, issue a certificate via Let’s Encrypt, and the service gets TLS without touching the container configuration. Without HTTPS, credentials travel in plain text over any network that is not fully private – so if you plan to access this from outside your home, the reverse proxy step is not optional.
OCR is one area where first-time users sometimes run into issues. The fat image includes English by default. To add other languages, set the environment variable LANGS to a space-separated list of Tesseract language codes – for example eng deu fra for English, German, and French. Those packs are downloaded when the container first starts, which can take a few minutes. If OCR jobs silently fail, check the container logs with docker logs stirling-pdf – a missing language pack is usually the culprit.
Keeping It Running and Up to Date
Stirling PDF releases updates frequently, sometimes multiple times a week. The easiest way to stay current is to run a tool like Watchtower alongside it in Docker Compose, which automatically pulls and restarts containers when new image versions are published. If you prefer manual control, a simple docker compose pull && docker compose up -d from the project directory is enough to update to the latest image without losing your configuration files, since those live in the mounted volume outside the container.
One thing to keep in mind: Stirling PDF’s settings and user accounts live in the /configs volume. If you ever recreate the container without that mount in place, you lose any customizations and have to reconfigure authentication from scratch. Backing up that config directory as part of your regular server backup routine – whether you use a tool like Restic for encrypted offsite backups or something simpler – costs almost nothing and avoids a tedious recovery scenario. The config directory is small, rarely more than a few kilobytes, but it carries all your security settings.
