Install with Docker

Docker is the recommended way to run a Stirling PDF server.

Quick start#

Create docker-compose.yml:

yaml

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - '8080:8080'
    volumes:
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/customFiles:/customFiles
      - ./stirling-data/pipeline:/pipeline
      - ./stirling-data/storage:/storage
      - ./stirling-data/tessdata:/usr/share/tessdata
    mem_limit: 4g
    restart: unless-stopped

Then start it:

bash

docker compose up -d

bash

docker run -d \
  --name stirling-pdf \
  -p 8080:8080 \
  -v ./stirling-data/configs:/configs \
  -v ./stirling-data/logs:/logs \
  -v ./stirling-data/customFiles:/customFiles \
  -v ./stirling-data/pipeline:/pipeline \
  -v ./stirling-data/storage:/storage \
  -v ./stirling-data/tessdata:/usr/share/tessdata \
  --memory 4g \
  --restart unless-stopped \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest

Open http://localhost:8080 and sign in as admin / stirling (see First login).

Choose an image#

Tag	Login and admin settings	Includes	Suggested memory
`latest`	Yes	LibreOffice, Tesseract, OCRmyPDF, WeasyPrint, Calibre, Ghostscript, QPDF and ImageMagick. No rar, so no PDF to CBR	4 GB
`latest-fat`	Yes	Everything in `latest`, plus the bundled AI engine, which stays off until you turn it on	6 GB, more with AI turned on
`latest-ultra-lite`	No	Core PDF tools only. No OCR, Office, HTML or ebook conversions	2 GB

Start with latest. Switch images by changing the tag and recreating the container. Your volumes carry over.

All images are built for amd64 and arm64.

Pin a version#

latest moves with every release. To control when you upgrade, use a version tag instead: <version>, <version>-fat or <version>-ultra-lite. Version numbers are listed on the releases page.

Other registries#

The images are also published to Docker Hub and GitHub. Use them if docker.stirlingpdf.com is unreachable:

bash

docker pull stirlingtools/stirling-pdf:latest
docker pull ghcr.io/stirling-tools/stirling-pdf:latest

Volumes#

Container path	What it holds
`/configs`	`settings.yml`, `custom_settings.yml`, the built-in database and its backups, and generated keys. Always mount this.
`/logs`	Log files.
`/customFiles`	Branding overrides and signature files. See UI and branding.
`/pipeline`	Watched and finished folders for folder scanning.
`/storage`	Files users save on the server. File storage is on by default, so always mount this.
`/usr/share/tessdata`	Extra OCR language files. See OCR languages.

The container runs as UID and GID 1000. If your host folders belong to another user, set PUID and PGID to that user's IDs. UMASK (default 022) sets permissions on new files.

Common settings#

Put settings in /configs/settings.yml, or pass them as environment variables. Any settings.yml key works either way: see Configuration.

yaml

system:
  defaultLocale: de-DE    # default language for new users
security:
  enableLogin: false      # run without login

bash

SYSTEM_DEFAULTLOCALE=de-DE
SECURITY_ENABLELOGIN=false

To serve on another port, change the host side of the mapping, for example '9000:8080'.

Updating Stirling PDF#

bash

docker compose pull
docker compose up -d

bash

docker pull docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
docker stop stirling-pdf
docker rm stirling-pdf
# then run your original docker run command again

Your data stays in the volumes. Back up /configs before a major upgrade, and read Upgrading from V1 if you are coming from V1.

Platform quick starts#

These platforms have community-maintained packages that wrap the Docker image. Report problems with the package to its own project, and Stirling PDF problems to the issue tracker.

Go to Apps → Discover Apps and search for "Stirling PDF".
Select Install, and change the port or storage if needed.
Open it from Apps → Installed.

Catalog listing: apps.truenas.com/catalog/stirling-pdf/.

Install the Community Applications plugin if you don't have it.
On the Apps tab, search for "Stirling PDF" and select Install.
Check the paths and variables in the template, then select Apply.

The template sets PUID=99 and PGID=100 for you.

The Community Scripts project has a one-line LXC installer. Run it from the Proxmox VE shell:

bash

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/stirling-pdf.sh)"

When it finishes, open http://<container-ip>:8080. Script details: community-scripts/ProxmoxVE.

To run Docker inside an LXC instead, enable nesting (pct set <ctid> -features nesting=1,keyctl=1), install Docker and use the compose file above.

Marius Hosting has step-by-step guides for Synology, UGREEN and Asustor.

Portainer: go to Stacks → Add stack and paste the compose file above.
CasaOS: use Install a customized app with the image docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest, port 8080, and bind mounts for the volumes.

For rootless Podman with systemd, save this as ~/.config/containers/systemd/stirling-pdf.container:

ini

[Unit]
Description=Stirling PDF

[Container]
Image=docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
PublishPort=8080:8080
Volume=%h/stirling-pdf/configs:/configs:Z
Volume=%h/stirling-pdf/logs:/logs:Z
Volume=%h/stirling-pdf/customFiles:/customFiles:Z
Volume=%h/stirling-pdf/pipeline:/pipeline:Z
Volume=%h/stirling-pdf/storage:/storage:Z
Volume=%h/stirling-pdf/tessdata:/usr/share/tessdata:Z
UserNS=keep-id:uid=1000,gid=1000
AutoUpdate=registry

[Install]
WantedBy=default.target

Then run systemctl --user daemon-reload && systemctl --user start stirling-pdf.

The :Z label is needed on SELinux distributions such as Fedora and RHEL. UserNS=keep-id maps your user to the container user, so you don't need PUID and PGID.

If the container won't start or the page won't load, check the logs.

Edit this page on GitHub