How to Self-Host Stirling PDF: 60+ PDF Tools Running on Your Own Server

What Stirling PDF provides

Stirling PDF is an open-source web application for working with PDF documents from a browser. Its available operations vary by release and image build, but the project includes tools for common jobs such as merging, splitting, rotating, reordering, compressing, converting, adding page numbers or watermarks, managing passwords, and processing scanned documents with OCR when the required components and language data are installed.

Self-hosting changes who controls the processing environment. Instead of uploading a contract, statement, form, or scanned document to an unrelated public website, users send it to a server administered by you. That can reduce third-party exposure, but it does not automatically guarantee that every byte remains only in memory or that nothing is retained. Temporary directories, application logs, configured pipelines, sharing features, authentication data, crash diagnostics, container storage, swap, backups, and administrator choices can all affect retention.

Treat Stirling PDF as a document-processing service, not as a magically stateless page. Review the behavior of the exact version you deploy, inspect its configured persistent paths, limit who can sign in, and establish a retention policy appropriate for the documents being processed.

The project evolves quickly, so this tutorial does not label an undated release as “latest.” Before deployment, select a release from the official Stirling PDF release list, read its release notes, and use an exact image tag supported by that release. Keep that version recorded in the deployment directory.

Architecture and security boundaries

A secure tunnel deployment has several distinct components. A remote browser connects to a public HTTPS address at the Localtonet relay. The Localtonet client on your machine maintains an outbound connection to that relay and forwards requests to Stirling PDF. Stirling PDF runs in a container, while selected configuration, logs, OCR data, and automation data remain on host-mounted storage.

Loopback binding is the safest default when both the Localtonet client and Docker run directly on the same host. Publishing 127.0.0.1:8080:8080 means port 8080 is reachable from that host but is not intentionally exposed on every LAN interface. This reduces accidental access from other machines on the local network.

The topology changes if Localtonet runs inside another container. A separate container cannot reach the host container through its own 127.0.0.1. In that arrangement, place both containers on an intentionally created Docker network and target the Stirling PDF service name and container port. Do not publish port 8080 to every host interface merely to make container-to-container communication convenient.

Prerequisites and deployment planning

Complete the following checks before creating the Compose project. They prevent common failures such as unsupported images, occupied ports, unwritable volumes, and updates that cannot be rolled back.

Host and container requirements

• A maintained operating system supported by Docker Engine or Docker Desktop.
• A current Docker installation with the Docker Compose plugin, invoked as docker compose.
• Enough free disk space for the selected container image, persistent data, logs, temporary processing, downloaded OCR data, and backups.
• Enough memory and CPU for the operations your users will run. OCR, compression, and office-document conversion can be considerably more demanding than page rotation or splitting.
• A non-root administrative account with permission to manage Docker and the deployment directory.
• A harmless test PDF that you are authorized to process.

There is no universal memory recommendation that fits every Stirling PDF workload. A one-page text PDF and a large scanned document have very different requirements. Start with conservative user access, monitor actual consumption, and increase resources based on measured workloads. Avoid publishing an instance before testing representative OCR and conversion jobs.

Confirm Docker and Compose

docker version
docker compose version
docker info

Resolve any Docker daemon or permission errors before continuing. Membership in the Docker administration group can effectively grant root-level control of the host, so assign it only to trusted administrators.

Select and record an exact release

Review the official release notes and choose a release tag rather than a moving tag such as latest. Confirm that the corresponding container image exists before changing production. A release tag makes the deployment reproducible and gives you a defined rollback target.

Container registry locations and tag conventions can change. Use the image reference published by the selected Stirling PDF release or its official documentation. The Compose example below uses a variable so the chosen reference is recorded outside the YAML file.

mkdir -p ~/stirling-pdf
cd ~/stirling-pdf
umask 077

cat > .env <<'EOF'
STIRLING_IMAGE=replace-with-the-official-image-reference
STIRLING_VERSION=replace-with-an-exact-release-tag
EOF

chmod 600 .env

Replace both placeholder values before starting the deployment. Do not continue with placeholders and do not substitute a floating latest tag.

Check architecture support

Do not assume that every image variant supports every processor architecture. This is especially important for ARM hosts and Raspberry Pi systems. Inspect the manifest for the exact image and tag selected from the official release:

docker buildx imagetools inspect \
  "${STIRLING_IMAGE}:${STIRLING_VERSION}"

Confirm that the manifest includes the host architecture reported by:

docker info --format '{{.Architecture}}'

If the architecture is absent, choose a documented compatible image or another host. Forcing an incompatible image through emulation can introduce poor performance and unexpected failures.

Check whether port 8080 is available

ss -ltn | grep ':8080 ' || true

On a system without ss, use its native network inspection tool. If another application already owns port 8080, select an unused host port and consistently substitute it in the Compose mapping, local tests, and Localtonet target.

Install Stirling PDF with Docker Compose

The baseline below deliberately keeps version-specific application settings out of the file. Stirling PDF has changed configuration names and supported image variants over time. Authentication and optional features should be added only after checking the configuration reference for the exact release you selected.

cd ~/stirling-pdf

mkdir -p \
  data/configs \
  data/logs \
  data/tessdata \
  data/pipeline \
  data/customFiles

chmod 700 data
chmod 700 data/configs data/logs data/tessdata data/pipeline data/customFiles

services:
  stirling-pdf:
    image: "${STIRLING_IMAGE}:${STIRLING_VERSION}"
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./data/configs:/configs
      - ./data/logs:/logs
      - ./data/tessdata:/usr/share/tessdata
      - ./data/pipeline:/pipeline
      - ./data/customFiles:/customFiles

docker compose config
docker compose config --images

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 stirling-pdf

curl --fail --show-error --location \
  --output /dev/null \
  --write-out 'HTTP %{http_code}\n' \
  http://127.0.0.1:8080/

Configure authentication and safe exposure

Authentication configuration is version-sensitive. Older examples found in forum posts may use environment variables, bootstrap credentials, role names, or recovery commands that no longer match the release you installed. Do not copy an undocumented password-reset command, and never delete the configuration directory as a casual password-recovery technique. That directory may contain settings, user information, or other state.

Use the security reference for the pinned release

Open the official Stirling PDF documentation and locate the security or login configuration for your exact version. Verify all of the following before adding settings:

• The supported setting that enables login.
• The current bootstrap process for creating the initial administrator.
• Whether credentials can be supplied through a protected file, a supported secret mechanism, or another method that keeps them out of a committed Compose file.
• The roles available in that version and which role can manage users.
• The supported password-change flow.
• The documented recovery procedure and which persistent files must be backed up first.

Store any local secret file with restrictive permissions and exclude it from version control. Do not place a real administrator password in compose.yaml, shell history, screenshots, support tickets, or a public repository. Environment variables are visible through some container inspection paths, so use a documented secret method if the selected release supports one.

Apply and test authentication

1. Stop the Localtonet tunnel if one already exists.
2. Add only the authentication settings documented for the pinned release.
3. Run docker compose config and check that secrets have not been unintentionally expanded into output you plan to save or share.
4. Recreate the container with docker compose up -d.
5. Open http://127.0.0.1:8080 from the host or through a local-only browser path.
6. Confirm that an unauthenticated private window receives a login page rather than access to PDF tools.
7. Sign in with the administrator account, change any bootstrap password if the version requires it, and create separate named users where appropriate.
8. Sign out and confirm that protected tools cannot be reached through browser history or a copied operation URL.

Review retention rather than assuming it

Self-hosting keeps the service under your administration, but retention depends on actual operation and configuration. Review:

• The host-mounted log directory and its rotation policy.
• Container writable layers and temporary directories.
• Pipeline input and output directories.
• Any enabled sharing or collaboration feature.
• Operating-system swap, snapshots, crash dumps, and backup destinations.
• Reverse-proxy or tunnel-adjacent access logs.

Avoid logging document names, user identifiers, or request details beyond what operations and security monitoring require. Backups containing authentication or application state should be encrypted and access-controlled.

OCR, image variants, and API automation

Choose an image by capabilities, not an old size estimate

Stirling PDF has offered different image variants, but names, included packages, download sizes, architecture support, and tool availability can change. Container size also varies by platform and release. Check the current installation documentation and image manifest before choosing a standard, expanded, or reduced image.

Validate the exact operations you require. If your workflow needs OCR, confirm that the image contains the required OCR engine. If it needs office-document conversion, confirm that the documented conversion component is present. A smaller image is not useful if it removes a required capability.

Manage OCR language data carefully

OCR language files must be compatible with the Tesseract version in the selected image and placed in the path expected by that release. The Compose example creates a persistent tessdata mount, but that alone does not install a language or prove compatibility.

Use the OCR installation procedure documented for the pinned Stirling PDF image. If language artifacts must be downloaded manually:

• Use the upstream location recommended by the release documentation.
• Pin a compatible artifact revision instead of downloading an unreviewed moving branch.
• Verify a published checksum or another trusted integrity indicator when available.
• Download to a temporary filename and move it into place only after verification succeeds.
• Set read permissions narrowly and avoid making the entire data directory world-writable.
• Restart the container only if the selected release documentation says a restart is required.
• Run a sample OCR job and verify the resulting text rather than relying only on a dropdown entry.

Build API clients from the deployed OpenAPI definition

API routes, multipart field names, authentication requirements, response types, and error codes can change between versions. For that reason, this guide does not publish unverified merge, OCR, or conversion commands. Open the API documentation exposed by your pinned deployment, if that feature is enabled, and compare it with the version's official documentation.

Before automating an endpoint, verify:

• The HTTP method and exact route.
• The required content type and multipart parameter names.
• Whether session authentication, an API key, or another credential is required.
• The success status and returned content type.
• The error response for an invalid PDF, unsupported operation, oversized request, and authentication failure.
• Client-side timeouts and safe handling of partial output files.

Pin the client integration to the server version you tested. Do not assume that every user-interface operation has a stable API contract across releases.

Perform a complete local functional test

A successful container start proves only that the process is running. Complete at least one real PDF workflow before enabling remote access.

docker compose logs --since=10m stirling-pdf
find data -maxdepth 3 -type f -printf '%p\n'

docker compose restart stirling-pdf
docker compose ps
curl --fail --show-error --location \
  --output /dev/null \
  --write-out 'HTTP %{http_code}\n' \
  http://127.0.0.1:8080/

Run additional tests for every feature that matters to your deployment. An OCR deployment should test a representative scan in each required language. A conversion deployment should test representative office documents with the fonts used by your organization.

Expose authenticated Stirling PDF through Localtonet

Localtonet exposes a service through an outbound client connection, so you do not need inbound router port forwarding, a public IP address, firewall changes, or a VPN setup. For this deployment, use an HTTP tunnel pointing to the local Stirling PDF address and port.

Complete the authentication and local functional tests first. The public tunnel should be the last step, not the first.

Localtonet terminates HTTPS at the public tunnel edge for an HTTP tunnel. The connection from the local client to http://127.0.0.1:8080 remains local HTTP in this topology. If the local hop crosses a machine, container host, or network you do not fully trust, redesign the deployment so that hop is appropriately protected.

Backups, updates, rollback, and routine operations

This deployment is not entirely stateless. The container can be replaced, but mounted configuration, authentication state, logs, OCR files, pipeline definitions, and custom files may persist. Whether a release uses a database or another persistent format is version-dependent. Treat every mounted directory as potentially important until the release documentation and your own inspection prove otherwise.

Backup checklist

• Record the exact image repository, release tag, and preferably the tested image digest.
• Back up compose.yaml and a redacted copy of deployment settings.
• Back up .env through a secure secrets process, not an unencrypted public repository.
• Back up configuration and authentication state from data/configs.
• Back up pipeline definitions if they are in use.
• Back up custom files and any manually managed OCR language data.
• Decide whether logs belong in backups according to your retention and incident-response policy.
• Encrypt backups and test restoration to an isolated directory.

For a consistent filesystem backup, schedule a maintenance window and stop the container before copying mutable persistent data:

cd ~/stirling-pdf
docker compose stop stirling-pdf

tar --create --gzip \
  --file "../stirling-pdf-backup-$(date +%Y%m%d-%H%M%S).tar.gz" \
  compose.yaml .env data

docker compose start stirling-pdf

The archive contains sensitive configuration and may contain authentication or log data. Move it to encrypted storage with restrictive access. The example does not replace a tested backup system or application-specific database procedure documented by a release.

Version-pinned update procedure

1. Read the target release notes and identify configuration, image, schema, security, and compatibility changes.
2. Confirm the target image supports your host architecture.
3. Back up all persistent mounts and record the currently working image tag or digest.
4. Test the update on a copy of the persistent data when the deployment is important or multi-user.
5. Change only STIRLING_VERSION in the protected .env file.
6. Pull the target image and validate the resolved Compose configuration.
7. Recreate the container, inspect logs, and repeat login and PDF functional tests.
8. Start or re-enable the Localtonet tunnel only after local verification succeeds.

docker compose pull
docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=200 stirling-pdf

Rollback procedure

A container rollback and a data rollback are different actions. If an update changes persistent data, merely restoring the old image may not be sufficient.

1. Stop the Localtonet tunnel to prevent user activity during recovery.
2. Stop the Stirling PDF container.
3. Preserve the failed deployment's logs and data for diagnosis.
4. Restore the pre-update persistent-data backup if the release modified incompatible state.
5. Restore the previous exact image tag or digest in .env.
6. Start the container locally and inspect its logs.
7. Repeat authentication, PDF processing, restart, and public tunnel tests.

Routine monitoring

docker compose ps
docker compose logs --since=24h stirling-pdf
docker stats --no-stream stirling-pdf
df -h
du -sh data/*

Review failed logins, processing errors, repeated large jobs, disk growth, container restarts, and memory pressure. Configure host-level log rotation and alerting appropriate to the sensitivity and availability needs of the service.

Troubleshooting common problems

Frequently asked questions