TL;DR
This is the evolution of my Paperless-ngx backup concept: automated daily backups and an optional copy stored elsewhere. Important: the Bash script shown below is a historical starting point, not a finished, verified 3-2-1 backup solution. The weekly retention policy discussed in the plan has not been implemented in that script.
Why bother with backups?
Paperless-ngx is great when you've digitized years of invoices, contracts and correspondence. But one dead disk, bad upgrade or accidental database change can make a mess of the archive. A backup is only useful when I can actually restore the data — preferably without a frantic evening of experimenting.
The idea
What I wanted:
- Automatic: A scheduled job, with failure reporting.
- Complete: Database, media, metadata and relevant configuration.
- Versioned: More than a single overwritten backup.
- Offsite-capable: Another independent destination such as a NAS or remote repository.
- Low impact: Run when the system is quiet.
The 3-2-1 goal
Three copies of the data, on at least two kinds of storage, with one copy kept elsewhere. It's a target to design and test for, not something you achieve just by putting two tarballs on the same disk.
Retention: plan versus reality
- Daily: The draft deletes local archives once they're older than seven days.
- Weekly: Retaining four weeks was planned but is not implemented.
- Monthly: Long-term retention and a true offsite copy still need to be added.
If your only backups are seven daily archives on one drive, you don't have a proper 3-2-1 setup. A restore test matters far more than a tidy-looking cron schedule.
The original backup script
Warning: historical draft — do not run this unreviewed in production. It contains an insufficiently guarded
rm -rfcleanup, a seven-day deletion rule, and an optionalrsync --delete. Its error handling and automatic recovery are also incomplete. I'm keeping the example as a record of the approach, not presenting it as production-ready code.
The intended sequence is to stop the Paperless web container, dump PostgreSQL, copy media and data, back up configuration, restart the web container, compress the result and optionally send a copy elsewhere.
This shows the original Bash draft, including its German comments and log messages, so no functional changes sneak in through translation.
#!/bin/bash
###############################################################################
# Paperless-NGX Backup Script
# Erstellt vollständige Backups inkl. Datenbank, Medien und Konfiguration
###############################################################################
# Konfiguration
PAPERLESS_DIR="/opt/paperless-ngx"
BACKUP_DIR="/mnt/backups/paperless"
COMPOSE_FILE="$PAPERLESS_DIR/docker-compose.yml"
RETENTION_DAYS=7
RETENTION_WEEKS=4
# Optional: Offsite Backup (NAS, rsync, rclone, etc.)
OFFSITE_ENABLED=false
OFFSITE_DEST="/mnt/nas/backups/paperless"
# Timestamp für Backup
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
BACKUP_NAME="paperless_backup_$TIMESTAMP"
TEMP_DIR="/tmp/$BACKUP_NAME"
# Logging
LOG_FILE="$BACKUP_DIR/backup.log"
log() {
echo "[$(date +'%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
}
# Backup-Verzeichnis erstellen
mkdir -p "$BACKUP_DIR"
mkdir -p "$TEMP_DIR"
log "=== Paperless-NGX Backup gestartet ==="
# 1. Container stoppen (optional - für konsistente Backups)
log "Stoppe Paperless-Container..."
cd "$PAPERLESS_DIR" || exit 1
docker compose -f "$COMPOSE_FILE" stop webserver
# 2. Datenbank exportieren
log "Exportiere PostgreSQL-Datenbank..."
docker compose -f "$COMPOSE_FILE" exec -T db pg_dump -U paperless paperless > "$TEMP_DIR/database.sql"
if [ $? -eq 0 ]; then
log "Datenbank-Export erfolgreich"
else
log "FEHLER: Datenbank-Export fehlgeschlagen!"
docker compose -f "$COMPOSE_FILE" start webserver
exit 1
fi
# 3. Media-Files kopieren
log "Kopiere Media-Files..."
cp -r "$PAPERLESS_DIR/media" "$TEMP_DIR/"
cp -r "$PAPERLESS_DIR/data" "$TEMP_DIR/"
# 4. Konfiguration sichern
log "Sichere Konfiguration..."
cp "$PAPERLESS_DIR/docker-compose.yml" "$TEMP_DIR/"
cp "$PAPERLESS_DIR/.env" "$TEMP_DIR/" 2>/dev/null || log "Keine .env Datei gefunden"
# 5. Container wieder starten
log "Starte Paperless-Container..."
docker compose -f "$COMPOSE_FILE" start webserver
# 6. Backup komprimieren
log "Komprimiere Backup..."
cd /tmp || exit 1
tar -czf "$BACKUP_DIR/$BACKUP_NAME.tar.gz" "$BACKUP_NAME"
if [ $? -eq 0 ]; then
log "Backup erfolgreich erstellt: $BACKUP_NAME.tar.gz"
BACKUP_SIZE=$(du -h "$BACKUP_DIR/$BACKUP_NAME.tar.gz" | cut -f1)
log "Backup-Größe: $BACKUP_SIZE"
else
log "FEHLER: Backup-Komprimierung fehlgeschlagen!"
exit 1
fi
# Temp-Verzeichnis aufräumen
rm -rf "$TEMP_DIR"
# 7. Alte Backups löschen (Rotation)
log "Lösche alte Backups..."
# Täglich: Behalte letzte 7 Tage
find "$BACKUP_DIR" -name "paperless_backup_*.tar.gz" -type f -mtime +$RETENTION_DAYS -delete
# Optional: Wöchentliche Backups behalten
# Hier könnte man zusätzliche Logik einbauen für wöchentliche/monatliche Backups
log "Alte Backups bereinigt"
# 8. Optional: Offsite-Backup
if [ "$OFFSITE_ENABLED" = true ]; then
log "Starte Offsite-Backup..."
mkdir -p "$OFFSITE_DEST"
# Beispiel mit rsync (anpassen je nach Setup)
rsync -avz --delete "$BACKUP_DIR/" "$OFFSITE_DEST/"
# Alternativ mit rclone (z.B. für Cloud-Storage):
# rclone sync "$BACKUP_DIR" "remote:paperless-backups"
if [ $? -eq 0 ]; then
log "Offsite-Backup erfolgreich"
else
log "WARNUNG: Offsite-Backup fehlgeschlagen!"
fi
fi
# Backup-Statistik
BACKUP_COUNT=$(ls -1 "$BACKUP_DIR"/paperless_backup_*.tar.gz 2>/dev/null | wc -l)
log "Anzahl vorhandener Backups: $BACKUP_COUNT"
log "=== Backup abgeschlossen ==="
# Optional: Benachrichtigung senden (z.B. via ntfy, gotify, email, etc.)
# curl -d "Paperless Backup erfolgreich: $BACKUP_SIZE" ntfy.sh/mein-paperless-backup
The cron job
The draft uses a nightly cron entry at 3 a.m. It also includes alternatives for every six hours, Sunday nights or weekdays.
Don't enable this job until the script has passed a manual test and the resulting backup has been restored successfully. Redirecting stdout to a log file alone isn't failure monitoring.
# Crontab bearbeiten
sudo crontab -e
# Paperless-NGX Backup - täglich um 3:00 Uhr
0 3 * * * /opt/paperless-ngx/scripts/backup.sh >> /mnt/backups/paperless/backup.log 2>&1
# Alle 6 Stunden
0 */6 * * * /opt/paperless-ngx/scripts/backup.sh
# Jeden Sonntag um 2 Uhr (wöchentlich)
0 2 * * 0 /opt/paperless-ngx/scripts/backup.sh
# Werktags um 1 Uhr nachts
0 1 * * 1-5 /opt/paperless-ngx/scripts/backup.sh
Installation and checks
1. Prepare the script
Create a dedicated scripts directory, open the backup file in an editor and review it carefully. The original German article ended abruptly at this step; the corrected version explicitly treats the script as unfinished.
2. Verify paths and permissions
- Do the Compose file, service names and directories match the actual installation?
- Is the backup destination really mounted, with enough capacity?
- Does the PostgreSQL dump use the correct database user and database name?
- Are database content, media and settings backed up consistently?
- Are archives and any copied
.envfile protected from unauthorized access?
3. Test a restore
Run a controlled backup first, then restore it into a separate test environment. Check the database, documents, media and metadata. Only then should a scheduled job be enabled.
4. Implement real retention and offsite protection
The RETENTION_WEEKS variable doesn't implement weekly retention. A proper daily/weekly/monthly strategy needs separate logic or a backup program built for that purpose. An unreviewed rsync --delete can propagate accidental deletion into the destination. Prefer versioned snapshots and independent, ideally immutable, copies.
My conclusion: the plan has useful parts, but dependable backups require independent storage, reliable failure handling and verified recovery.
# Verzeichnis für Scripts erstellen
sudo mkdir -p /opt/paperless-ngx/scripts
# Script erstellen
sudo nano /opt/paperless-ngx/scripts/backup.sh
# Script in den Editor einfügen, sorgfältig prüfen und speichern
# Den Entwurf NICHT ohne Tests produktiv aktivieren
Alternative: use the official Paperless exporter
For a new setup, I'd seriously consider starting with Paperless-ngx's own document_exporter. According to the official Paperless-ngx documentation, it exports documents, thumbnails, metadata and database contents. The matching document_importer can bring that export into a fresh installation.
A sensible workflow is to:
- Avoid ongoing document ingestion while creating the export.
- Put the export directory on persistent storage, outside the directories being exported.
- Back it up into an encrypted, versioned and independent repository — for example with Restic or Borg on a NAS and another offsite destination.
- Configure actual retention in the backup tool: for instance, seven daily, four weekly and a few monthly recovery points.
- Keep track of the Paperless version: exports can't necessarily be imported into a different application version.
- Regenerate API tokens after import; those aren't included in the export.
- Practice and document a full restore.
That's much sturdier than inventing backup retention around a shell command that deletes files.