Stirling PDF on Ubuntu 24.04 on Azure User Guide

Overview

Stirling PDF is the open source, self-hosted PDF toolkit. It gives you 50+ PDF operations in a single clean web UI - merge, split, convert to and from Office formats and images, OCR scanned pages, compress, sign, redact, add watermarks, fill and flatten forms, and much more - with every document processed locally on your own VM, so nothing is ever sent to a third-party cloud. The cloudimg image installs Docker CE from the official Docker repository and runs Stirling PDF 2.14.1 as a container (managed by Docker with a restart policy), bound to the loopback connector 127.0.0.1:8080 behind an nginx reverse proxy on port 80. nginx protects the whole toolkit with HTTP Basic Auth, and a unique login password is generated on the first boot of every VM. Stirling's configuration, custom files and logs live on a dedicated Azure data disk. Backed by 24/7 cloudimg support.

What is included:

• Stirling PDF 2.14.1 running as a container managed by Docker
• Docker CE preinstalled from the official Docker apt repository
• The Stirling PDF web UI on :80, fronted by nginx with HTTP Basic Auth
• A unique login password generated on first boot and recorded in a root-only file
• A dedicated Azure data disk at /var/lib/stirling-pdf holding configuration, custom files and logs
• docker.service + nginx.service as systemd units, enabled and active
• An unauthenticated /healthz endpoint for Azure Load Balancer health probes
• Generous upload limits (nginx client_max_body_size 512m) for large PDFs
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2ms (2 vCPU / 8 GiB RAM) is a reasonable starting point; size up if you process large PDFs, run OCR on many pages at once, or expect concurrent users. NSG inbound: allow 22/tcp from your management network and 80/tcp. Stirling PDF serves plain HTTP on port 80; for production, terminate TLS in front of it with your own domain and consider adding 443/tcp (see Maintenance).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Stirling PDF by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the dedicated data disk on the Disks tab, then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name stirling-pdf \
  --image <marketplace-image-urn> \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name stirling-pdf --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active docker.service nginx.service

Both report active. Docker manages the Stirling PDF container (bound to the loopback connector 127.0.0.1:8080), and nginx fronts it on port 80 behind HTTP Basic Auth. Stirling's configuration, custom files and logs live on the dedicated Azure data disk mounted at /var/lib/stirling-pdf.

Step 5 - Retrieve your login credentials

Stirling PDF is protected by HTTP Basic Auth (user admin). The password is generated uniquely on the first boot of your VM and written to a root-only file:

sudo cat /root/stirling-pdf-credentials.txt

This file contains STIRLING_PDF_USERNAME, STIRLING_PDF_PASSWORD and the URL to open. Store the password somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint for load balancers and probes:

curl -s http://localhost/healthz

It returns ok. This endpoint never requires authentication, so it is safe for an Azure Load Balancer health probe.

Step 7 - Confirm the login password is enforced

Because a password is set on first boot, an unauthenticated request to the toolkit is rejected (HTTP 401), so nobody reaches your documents without the password:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/

It prints 401. A wrong password is also rejected with 401; only the per-VM password from Step 5 returns 200. You can confirm this in the browser in the next step.

Step 8 - Sign in to the toolkit

Browse to http://<vm-public-ip>/. Your browser prompts for HTTP Basic Auth credentials; enter admin and the password from Step 5. Once signed in, you land on the tool grid - every PDF operation Stirling PDF offers, grouped by category (General, Convert, Security, Sign, Advanced and more), with a search box to find a specific tool quickly.

Step 9 - Merge or convert a PDF

Open Merge (or any tool - Split, Convert to/from Word/Image, Compress, OCR, Sign, Redact, Watermark and 50+ others follow the same pattern), drag in your PDF file(s), and configure the operation's options in the panel.

Step 10 - Browse the tool categories

The left-hand navigation groups every operation - Convert, Security, Sign, Edit, Advanced and more - so you can jump straight to the tool you need without searching.

Step 11 - Review account and settings

The account menu shows the signed-in session and links to the toolkit's settings, where you can adjust language, theme and other preferences.

Step 12 - Confirm data lives on the dedicated disk

Stirling's configuration, custom files and logs are stored under /var/lib/stirling-pdf on the dedicated Azure data disk (bind-mounted into the container as /configs, /customFiles and /logs), so they survive OS changes and can be resized independently:

findmnt /var/lib/stirling-pdf

The mount is backed by a separate Azure data disk captured into the image and re-provisioned on every VM.

Maintenance

• Password: the Basic Auth password is set on first boot. To change it, run sudo sh -c 'printf "admin:%s\n" "$(openssl passwd -apr1 NEW_PASSWORD)" > /var/lib/stirling-pdf/.htpasswd' && sudo systemctl reload nginx.
• Custom files & pipelines: the /customFiles and /pipeline directories under /var/lib/stirling-pdf let you add custom stamps, watermark images and automation pipeline configs - see the Stirling PDF documentation for details.
• OCR languages: additional Tesseract language packs can be added to the container's tessdata volume if you need OCR in languages beyond English.
• Upgrades: Stirling PDF runs as the stirling-pdf container from the pinned stirlingtools/stirling-pdf:2.14.1 image; to upgrade, pull a newer tag, remove the container and re-run it with the same -v /var/lib/stirling-pdf/configs:/configs -v /var/lib/stirling-pdf/logs:/logs -v /var/lib/stirling-pdf/customFiles:/customFiles mounts so your configuration is preserved.
• Storage: all Stirling state lives under /var/lib/stirling-pdf on the data disk; back up that volume to protect your configuration and custom files.
• TLS: Stirling PDF serves plain HTTP on port 80; front it with TLS (e.g. certbot with your own domain) before production use.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.
• License: Stirling PDF's core is MIT licensed. This image ships the free Community edition with no Pro/Enterprise license key; some optional proprietary modules described in the upstream project are not included.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.