Updated: September 14, 2026

Paperless-ngx Document Management and Backup#

This note documents the Paperless-ngx deployment on HP1Docker (10.1.2.202), its document locations, and the file-level backup path to HP1TrueNAS (10.1.2.201). It reflects the live configuration inspected on 2026-09-14.

1. Service architecture#

Paperless-ngx runs from /home/marc/docker-compose/paperless on HP1Docker using Docker Compose:

The Compose definition is stored at:

/home/marc/docker-compose/paperless/docker-compose.yaml

2. Document intake and storage#

The active Paperless document store is the local ext4 filesystem mounted at /mnt/paperless on HP1Docker.

The container mappings are:

/mnt/paperless/media   -> /usr/src/paperless/media
/mnt/paperless/export  -> /usr/src/paperless/export
/mnt/paperless/consume -> /usr/src/paperless/consume

The intake directory is itself backed by the UNAS-Pro share //10.1.2.2/Paperless_consume. Paperless polls the consume directory every 30 seconds. The Samba paperless share documented in Linux - Initial Setup exposes the originals directory directly at /mnt/paperless/media/documents/originals/.

Paperless metadata such as tags, correspondents, document types, search state, and processing state is held in PostgreSQL rather than in the document filenames. Redis handles task queuing. Tika, Gotenberg, and Paperless GPT participate in extraction, conversion, OCR, and classification.

3. Paperless to UNAS-Pro synchronization#

The active synchronization script is:

/home/marc/docker-compose/paperless/scripts/paperless-sync.sh

It runs from root’s crontab on HP1Docker:

00 * * * * /home/marc/docker-compose/paperless/scripts/paperless-sync.sh

The synchronization is one-way and mirrors the Paperless originals directory:

Source:      /mnt/paperless/media/documents/originals/
Destination: /mnt/Documents/Paperless/

/mnt/Documents is a CIFS mount of the UNAS-Pro Documents share:

//10.1.2.2/Documents -> /mnt/Documents

The script:

• Verifies that /mnt/Documents is mounted as CIFS.

• Requires /mnt/Documents/.paperless-canary before running.

• Uses rsync --delete so the destination mirrors the source.

• Excludes operating-system, synchronization, and temporary files using scripts/sync_ignore.txt.

• Preserves overwritten and deleted destination files under:

  /mnt/Documents/Paperless/.HP1Docker_SafetyNet/<timestamp>/

• Removes safety copies older than 30 days and prunes older copies when the destination reaches 80% usage.

• Writes timestamped logs under:

  /home/marc/docker-compose/paperless/logs/Rsync/

The latest inspected run completed successfully with 7,459 entries, 6,641 regular files, 25.35 GB of source data, and no created, deleted, or transferred files. The mirror was already current.

See Cron Jobs for the documented Paperless synchronization procedure.

4. UNAS-Pro to HP1TrueNAS backup#

HP1TrueNAS (10.1.2.201) pulls the UNAS-Pro Documents rsync module hourly. The backup target is:

/mnt/RaidZ1SSDPool8TB/HP1UNASBackup/Documents/

The Paperless subtree therefore lands at:

/mnt/RaidZ1SSDPool8TB/HP1UNASBackup/Documents/Paperless/

The local source script is:

/Users/marc/Scripts/TrueNAS/HP1_UNAS_Pull_Backup.sh

Its relevant source and destination are:

Source:      root@10.1.2.2::Documents/
Destination: /mnt/RaidZ1SSDPool8TB/HP1UNASBackup/Documents/

The HP1TrueNAS job also uses --delete and places deleted or replaced files in a dated backup directory under:

/mnt/RaidZ1SSDPool8TB/HP1UNASBackup/YYYY-MM-DD_Rsync_deleted/

HP1TrueNAS logs are stored under:

/mnt/homes/unas_backup/

The latest inspected HP1TrueNAS log showed a successful Documents pull with a total size of 25,349,290,498 bytes. The destination contained the Paperless directory and occupied approximately 22 GB.

The fleet schedule and dataset mapping are documented in Unifi UNAS-Pro Backup Strategy.

5. End-to-end flow#

UNAS-Pro Paperless_consume share
        ↓
HP1Docker /mnt/paperless/consume
        ↓ Paperless processing, OCR, metadata, and indexing
HP1Docker /mnt/paperless/media/documents/originals
        ↓ hourly rsync at minute 00
UNAS-Pro Documents/Paperless
        ↓ hourly HP1TrueNAS pull at minute 00
HP1TrueNAS HP1UNASBackup/Documents/Paperless

This is not a direct Paperless-to-HP1TrueNAS transfer. HP1TrueNAS receives the files indirectly through the UNAS-Pro Documents share.

6. Backup coverage and recovery limitations#

The Paperless synchronization chain protects the original document files. It does not constitute a complete Paperless application backup.

Not included in the Paperless file mirror are:

• PostgreSQL metadata and Paperless database state.
• Tags, correspondents, document types, saved views, and search/index metadata.
• Redis task state.
• Paperless application data under the Compose data directory.
• Paperless GPT working data under /mnt/paperless/gpt.
• Archive and thumbnail directories, because the synchronization source is specifically documents/originals/.

The PostgreSQL container has a separate daily database-backup service writing to data/db_backups, but that directory is not part of the Paperless-to-UNAS document synchronization source. A complete disaster-recovery plan must therefore protect both the document files and the Paperless database/application data.

7. Operational observations#

1. Both synchronization stages are scheduled at minute 00. There is no configured offset, so HP1TrueNAS can begin pulling while the Paperless-to-UNAS rsync is still finishing. It may therefore capture the previous completed mirror during an overlap.
2. The current live paperless-sync.sh includes the SafetyNet backup options and uses the logs/Rsync/ directory. Some older instructions in Cron Jobs show an earlier version of the script and should not be treated as the authoritative current implementation.
3. The HP1TrueNAS source uses rsync module syntax (root@10.1.2.2::Documents/), so the UNAS-Pro Documents module is the actual upstream backup source.
4. The .paperless-canary is a safety control, not a Paperless document. It is intentionally required before the first-stage mirror can run.

Related notes#

• Backup Strategies
• Cron Jobs
• Unifi UNAS-Pro Backup Strategy
• Linux - Initial Setup
• Backrest & Restic Google Drive Backup Setup