Skip to content
fipityPublic

About

Self-hosted private PDF toolkit for a home network: Stirling-PDF + ConvertX on Docker Compose

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

pdf-tools

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.

First-time setup

cp .env.example .env    # then set SERVER_URL and generate the secrets
docker compose up -d
  1. Open ConvertX straight away and create its account. Anyone who reaches it first can register the only account.
  2. Log in to Stirling with the admin details from .env.
  3. 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.

Start, stop, update

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     # logs

Both 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 -d

Versions 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.

Where data is stored

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.

Back up signatures and settings

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 start

The 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

Usage notes

  • 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 vips option 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 .env only 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.

License

The files in this repo are MIT licensed (see LICENSE). Stirling-PDF and ConvertX are separate projects under their own licenses.

About

Self-hosted private PDF toolkit for a home network: Stirling-PDF + ConvertX on Docker Compose

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors