Stirling-PDF: The PDF Toolbox on Your Own Server

"Merge PDF online", "compress PDF free" - for tasks like these you'd usually upload your documents to some web service, often with confidential content. Stirling-PDF does the same on your own server: over 50 PDF tools, and your files never leave your control. What are we building? A complete PDF toolbox with Stirling-PDF v2.14.2 behind Traefik, secured with a login. By the end you merge PDFs, compress and rotate them, convert between formats, make scanned documents searchable with OCR, redact content, add passwords or watermarks - all in the browser, all locally. Exactly the right tool to prepare documents from Paperless or Nextcloud. Prerequisites - A server with Traefik running and Docker Compose - A subdomain pointing at the server - YOUR_DOMAIN below Step by step Step 1: Project and Compose file Stirling-PDF is stateless at its core - it processes files and returns them without storing them permanently. Only configuration and OCR language data live in volumes. Create the project: mkdir -p /opt/stirling/data /opt/stirling/configs && cd /opt/stirling The compose.yaml - replace YOUR_DOMAIN : services: stirling-pdf: image: stirlingtools/stirling-pdf:2.14.2 restart: unless-stopped volumes: - ./data:/usr/share/tessdata # OCR language data - ./configs:/configs # configuration environment: LANGS: 'en_GB' # UI language networks: [proxy] labels: - "traefik.enable=true" - "traefik.http.routers.stirling.rule=Host(YOUR_DOMAIN)" - "traefik.http.routers.stirling.entrypoints=websecure" - "traefik.http.routers.stirling.tls.certresolver=le" - "traefik.http.services.stirling.loadbalancer.server.port=8080" networks: proxy: external: true Step 2: Start and wait for "healthy" docker compose up -d The image ships its own health check, and Traefik only routes to the container once it's healthy - which takes about 20-30 seconds after start (the Java application needs a moment). Check: docker compose ps NAME IMAGE STATUS stirling-stirling-pdf-1 stirlingtools/stirling-pdf:2.14.2 Up (healthy) Step 3: First login and forced password change Open https://YOUR_DOMAIN/ . Stirling-PDF v2 is protected by a login by default - an important difference from many other tools, and one you shouldn't disable if the service is publicly reachable. Log in with the default credentials admin / stirling . On first login Stirling-PDF immediately forces a password change - good. Set a strong password; then log in again with the new one. ⚠️ Change the default credentials immediately admin /stirling are publicly known. As long as this password is in effect, your toolbox is open to anyone who knows the domain. The forced change on first login is intentional - don't skip it, and choose a real password. Step 4: The toolbox After login you see the interface: your files on the left, the full tool catalog on the right, grouped into categories like Signing, Document security and Verification. Getting started is always the same: load a PDF via Upload from computer (or drag & drop), then pick the tool you want on the right. The file appears in the built-in viewer: The most useful tools in everyday use: - Merge / Split: combine multiple PDFs into one or separate out pages. - Compress: reduce file size for sending by email. - Convert: PDF ↔ image, Word/Office → PDF and back. - OCR & clean scans: make scanned documents searchable (that's what the tessdata language data is for). - Redact: permanently remove confidential parts - not just paint over them in black. Step 5: Add OCR languages (optional) For OCR in a given language, Stirling-PDF needs the matching Tesseract language data. The official image ships common languages; if one is missing, drop the corresponding .traineddata file into the mounted data folder (/usr/share/tessdata ). After that the language is available in the OCR tool. When things go wrong The page doesn't load (Traefik 404) even though the container is running. The health check isn't healthy yet - Traefik deliberately doesn't route then. Wait 20-30 seconds after start; check the status with docker inspect -f '{{.State.Health.Status}}' stirling-stirling-pdf-1 . Login with admin /stirling fails. Either the password was already changed (then use the new one), or the config in the configs volume is inconsistent. To reset, stop the app and check the user config in the configs folder; if in doubt clear the folder (note: this resets all settings). OCR can't find my language. The matching .traineddata is missing from the tessdata volume. Get the file from the Tesseract language packs and place it in the data folder (see step 5). A conversion (e.g. Office → PDF) fails. Such conversions need extra tools (LibreOffice) that are only included in the larger image variants. For the full feature set use the -fat variant of the image (stirlingtools/stirling-pdf:2.14.2-fat ). Large files cause errors or long waits. OCR and conversion are memory-intensive. On a small VPS RAM can run short - then either process smaller files or move to a larger product. Maintenance & backups - Updates. Occasionally bump the image tag ( stirlingtools/stirling-pdf:2.14.2 ) to the current version anddocker compose up -d . Stirling-PDF is actively developed and gets new tools frequently; a look at the release notes is worthwhile. The rest runs through your normal update process. - The backup is small. Because the file processing is stateless, you only need to back up the configs folder (login, settings) and any custom OCR language data - best with Restic. You store the processed PDFs yourself anyway. - Security. The login is the first line of defense - keep the admin password strong and current. Since potentially confidential documents pass through here, running behind HTTPS (Traefik) and a login is mandatory; a publicly reachable Stirling-PDF without a password would be a serious data leak. This post first appeared on serverkueche.de. Top comments (0)