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

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn cloudimg1647283583153:stirling-pdf-ubuntu-24-04:default:latest

az vm create \
  --resource-group <your-rg> \
  --name stirling-pdf \
  --image cloudimg1647283583153:stirling-pdf-ubuntu-24-04:default:latest \
  --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

First boot takes a few minutes. On its first boot the VM finishes its per-VM setup in the background (generating this VM's own credentials and starting the services). If you connect as soon as the VM shows as running, wait for that setup to complete before continuing:

bash sudo cloud-init status --wait

It prints status: done when the VM is ready. Credentials and services described below are only present after that.

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.