Private PDF toolkit for the home network. Everything runs on this server.
| App | URL | Use it for |
|---|---|---|
| Stirling-PDF 3.3.0 | http://<server-ip>:8092 |
View, edit, annotate, sign, fill forms, page operations, all conversions except HEIC |
| ConvertX 0.20.0 | http://<server-ip>:8093 |
HEIC to PDF (Stirling can't read HEIC) |
Intended for a trusted home network only. It uses plain HTTP, so don't expose it to the internet.
cp .env.example .env # then set SERVER_URL and generate the secrets
docker compose up -d- Open ConvertX straight away and create its account. Anyone who reaches it first can register the only account.
- Log in to Stirling with the admin details from
.env. - Reserve the server's IP on your router so the URLs keep working.
If your user ID isn't 1000, change PUID and PGID in compose.yaml.
Run these from ~/docker/pdf-tools.
docker compose up -d # start
docker compose stop # stop
docker compose restart # restart
docker compose ps # status
docker compose logs -f # logsBoth containers use restart: unless-stopped, so they come back after a reboot unless you stopped them.
To update: back up first, change the version tag in compose.yaml, then run:
docker compose pull && docker compose up -dVersions are pinned on purpose. Upstream plans to remove LibreOffice from Stirling shortly after 3.3.0, so re-test Word conversions after updating. To roll back, restore the old tag and your backup.
Everything is under ~/docker/pdf-tools/:
| Path | Contents |
|---|---|
.env |
Passwords and secrets |
compose.yaml |
Container configuration |
data/stirling/customFiles/signatures/ |
Saved signatures (one folder per user) |
data/stirling/configs/ |
Stirling settings, user database, keys, nightly DB backups |
data/stirling/logs/ |
Stirling logs |
data/convertx/ |
ConvertX account database, plus files for jobs still awaiting cleanup |
File retention
- Stirling doesn't store your PDFs on the server. Its temp files normally go when a job finishes; leftovers are removed after about 1 hour.
- ConvertX deletes jobs older than 1 hour on an hourly check, so a file can last up to about 2 hours.
- Stirling's PDF Library sidebar lives in each device's browser, not on the server. Remove files there when you're done, especially on a shared device.
This stops the apps for a few seconds so the database copy is consistent:
cd ~/docker/pdf-tools
docker compose stop
tar czf ~/pdf-tools-backup-$(date +%F).tar.gz .env compose.yaml data/stirling/configs data/stirling/customFiles
docker compose startThe archive contains your password file and signature images, so store it somewhere private.
To restore:
cd ~/docker/pdf-tools
docker compose stop
tar xzf ~/pdf-tools-backup-YYYY-MM-DD.tar.gz
docker compose start- Filling forms: save with Apply Changes or Download PDF in the "Form Fields" bar. The download icon in the top toolbar skips unapplied form entries.
- Signatures: add them with the Sign tool. They're saved to your account (20 maximum) and appear on any device you log in from. Applied signatures are PDF stamp annotations; run the Flatten tool to burn them into the page. Flatten turns pages into images, so text can't be selected or searched afterwards unless you OCR it.
- HEIC in ConvertX: choose PDF with ImageMagick or GraphicsMagick. The
vipsoption fails for PDF. The page matches the photo's pixel size, so it's very large; use Stirling's page-size tool if you need A4. - PDF to Word: defaults to Stirling Office Convert (beta), which gives real headings and tables. To use LibreOffice, pick it in the Convert tool's engine selector. Scanned PDFs need OCR first.
- Passwords: change Stirling's under Settings, Account. The value in
.envonly applies to the first start, so it will then be out of date. - Privacy settings are environment variables in
compose.yaml, which override the admin UI. Analytics, update checks and Stirling account linking are off.
The files in this repo are MIT licensed (see LICENSE). Stirling-PDF and ConvertX are separate projects under their own licenses.