What is Stirling PDF?
Stirling PDF is a self-hosted PDF toolbox with editing, merging, splitting, compression, conversion and OCR tools. A shared instance gives your devices and team a consistent place to process documents. It also provides APIs for integrations. Explore the official project.
Everyday document jobs
Combine files, rearrange pages and prepare smaller PDFs for a client, supplier or application form.
Searchable scans
Use OCR when you need to find or copy text from scanned pages, then check the result against the original.
A controlled workspace
Choose who can sign in, manage the server's storage and maintain your own recovery copies.
Version 3.3.0 arrived on 5 November 2026 with conversion improvements, security fixes and lower memory use for some large-file operations. Its Office Convert work remains beta, and the deprecated backend PDF text-editing API has been removed. Check integrations and representative documents when upgrading. Read the 3.3.0 release notes.
Choose a VPS for PDF processing
The upstream sizing guide suggests 2–4 CPU cores and 4 GB RAM for a small installation. OCR, Office conversion and rendering large PDFs can demand substantially more memory and CPU. For the 4 GB container limit below, our practical starting point is a VPS with around 8 GB RAM, leaving room for Linux, Docker and Caddy. Measure your own documents and concurrency before choosing long-term capacity. Review Stirling PDF's sizing guidance.
Use a current Ubuntu LTS VPS with Docker Engine and the Compose plugin installed, plus a sudo-capable administrator. Docker commands below assume your account can access Docker. If your installation requires sudo, use it consistently for those commands. This walkthrough uses a host-installed Caddy reverse proxy. Create a DNS A record for pdf.example.com pointing to the VPS. Add an AAAA record when IPv6 reachability is working. Replace that hostname throughout the examples.
1. Prepare the deployment and administrator
Confirm Docker and Compose are available, then create a dedicated directory.
docker version
docker compose version
mkdir -p ~/stirling-pdf
cd ~/stirling-pdf
umask 077
touch .env
chmod 600 .env
openssl rand -hex 32
Copy the generated password into .env, replacing the placeholder below. Keep it in your password manager.
STIRLING_HOSTNAME=pdf.example.com
STIRLING_ADMIN_PASSWORD=REPLACE_WITH_THE_GENERATED_PASSWORD
The initial administrator settings apply when the user database is empty. They let you choose credentials before first startup. Later password changes belong in the application account controls. Review administrator setup.
2. Create the Docker Compose configuration
Save this as compose.yaml in the same directory. The standard versioned image includes login and conversion tools. The named volumes retain application state across container recreation. Compare the official Docker installation.
name: stirling-pdf
services:
stirling-pdf:
image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:3.3.0
restart: unless-stopped
mem_limit: 4g
ports:
- "127.0.0.1:8080:8080"
environment:
SECURITY_ENABLELOGIN: "true"
SECURITY_INITIALLOGIN_USERNAME: admin
SECURITY_INITIALLOGIN_PASSWORD: ${STIRLING_ADMIN_PASSWORD:?Set the administrator password in .env}
SYSTEM_FRONTENDURL: https://${STIRLING_HOSTNAME:?Set the hostname in .env}
SYSTEM_BACKENDURL: https://${STIRLING_HOSTNAME}
SYSTEM_FILEUPLOADLIMIT: 100MB
SYSTEM_ENABLEANALYTICS: "false"
volumes:
- configs:/configs
- storage:/storage
- custom-files:/customFiles
- logs:/logs
- pipeline:/pipeline
- tessdata:/usr/share/tessdata
volumes:
configs:
storage:
custom-files:
logs:
pipeline:
tessdata:
The backend is bound to the host's loopback address. Caddy on that host can reach port 8080. Public traffic enters through HTTPS. Use a current Docker Engine because older releases had a localhost-publishing exposure on the same network segment. Read Docker's port-publishing behaviour.
The example caps uploads at 100 MB. Environment variables override file and dashboard settings, so edit the Compose value and recreate the service when changing that limit. Review configuration precedence.
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose logs --tail=100 stirling-pdf
curl --fail http://127.0.0.1:8080/api/v1/info/status
Allow startup to finish before checking the status endpoint. Keep .env private and use config --quiet for validation, since a full rendered configuration contains the resolved administrator password.
3. Put Stirling PDF behind HTTPS
Install Caddy using its official Ubuntu package instructions if it is not already present. The package supplies a systemd service. Add this site block to /etc/caddy/Caddyfile, keeping existing sites in that file. Follow Caddy's installation instructions.
pdf.example.com {
reverse_proxy 127.0.0.1:8080 {
header_up X-Forwarded-Port 443
flush_interval -1
}
}
Caddy supplies the forwarded host and protocol headers. The additional port header identifies the public HTTPS port, and immediate flushing suits streamed responses. Review the reverse proxy options.
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
Allow inbound TCP 80 and 443 through the relevant firewalls, with SSH restricted to your administrators. Caddy can issue and renew a public certificate when the hostname resolves correctly and those ports reach it. Visit https://pdf.example.com and sign in with your chosen credentials. Check automatic HTTPS requirements.
Verify the login page in a fresh signed-out browser. The application's status endpoint is intentionally available without login. If you later add another proxy, align its upload limits and long-running request timeouts with the application. Review the production checklist.
4. Test your actual document workflow
- Merge two small PDFs. Check the downloaded file's page order and readability.
- Compress a sample scan. Compare file size and readable text at the quality your users need.
- Run OCR on a scanned page. Select the right language and verify names, numbers and search results.
- Restart the container. Confirm your account and a deliberately saved test file are still present.
docker compose restart stirling-pdf
docker stats --no-stream
Use non-sensitive samples while checking the deployment. Watch memory during the largest jobs you expect to run, and increase capacity or reduce simultaneous work around those observations.
Server file storage is enabled by default. The storage volume therefore matters alongside configuration and the database. Review saved files, sharing permissions and retention as part of operating the service. Read the file-storage settings.
Review accounts, privacy and licence limits
The self-hosted Free plan currently supports five users. Paid plans add features including external databases and S3 file storage. Processor automation, AI features and API-key tool calls have processing allowances. Check the applicable plan before building a team workflow or API integration. Compare the current server plans.
The Compose example disables documented application analytics with SYSTEM_ENABLEANALYTICS=false. Review external AI providers, cloud connections and integrations separately when deciding how documents may be processed. Review analytics and telemetry controls.
Back up the configuration and saved files
Keep the deployment files, secrets, Caddy configuration and application volumes in your recovery plan. The configs volume contains the built-in database, settings and generated keys. Preserve saved documents in storage and any custom assets. Take a consistent application copy, using a maintenance window to stop writes when required, and test recovery on an isolated instance. Review upstream backup guidance.
New HYEHOST Cloud VPS orders include one customer backup slot, with paid extras and daily, weekly or selected-day scheduling available. Create a recovery point before a major application change. Your VM's Backups tab shows its actual allowance. Independent encrypted archives can also be kept on a Storage Box using your chosen backup software.
For an update, read the target release notes, make a recoverable copy, change the pinned image version and run the following commands. Recheck login, saved files and your sample jobs. Database changes can require restoring the pre-update data when rolling back.
docker compose config --quiet
docker compose pull stirling-pdf
docker compose up -d stirling-pdf
docker compose logs --tail=100 stirling-pdf
Common Stirling PDF Docker problems
The administrator password did not change
Initial-login variables only apply to a fresh user database. Use the account controls for an existing installation and preserve its data.
Uploads fail at a predictable size
Check the Compose upload limit and every proxy in front of the service. Apply environment changes by recreating the container.
OCR jobs stop or the service restarts
Inspect logs, container memory and host memory during a small test. Reduce concurrent work or add capacity for the documents involved.
Stirling PDF VPS installation FAQ
Is Stirling PDF free to self-host?
A self-hosted server starts on the Free plan, which currently allows five users. Paid plans add features, and processing allowances apply to some automation, AI and API use. Check the current licence terms for your workflow.
How much RAM does Stirling PDF need on a VPS?
The standard image suggests about 4 GB of container memory. This guide recommends around 8 GB of VPS RAM to leave room for the operating system, Docker and Caddy. Large files, OCR and simultaneous jobs can need more.
Does the Stirling PDF Docker image include login?
The standard image used here supports login. Keep it enabled and configure the initial administrator before the first startup. The ultra-lite image has no login support.
Can I run Stirling PDF over HTTPS?
Yes. This guide uses Caddy on the Docker host to provide HTTPS and proxy requests to a backend bound to 127.0.0.1 on port 8080. Set the public hostname correctly and verify signed-out access requires login.
Will saved files survive a Docker container update?
Persist the configuration and storage volumes, along with any other application assets you use. Named volumes survive normal container recreation. Keep independent backups and check saved files after an update.
Can HYEHOST back up the VPS running Stirling PDF?
New Cloud VPS orders include one customer backup slot, with paid extras and scheduling available. Check the VM Backups tab for its allowance. Keep application-level recovery copies of the configuration and saved documents as well.

