📦 Paperless Backup

An automated Docker-based backup system for Paperless-ngx with email notifications and retention policies.

Features

🔄 Automated Backups - Time-scheduled backups with cron integration
📧 Email Notifications - Success and failure alerts via SMTP
🧹 Retention Policy - Automatic cleanup of old backups

Available on

🚀 Quick Start

minimal Docker Run

docker run -d \
  --name paperless-backup \
  -e PAPERLESS_CONTAINER_NAME=paperless \
  -e PAPERLESS_EXPORT_DIR=../export \
  -v /path/to/paperless/export:/export \
  -v /path/to/backups:/backups \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/rossberi/paperless-backup:latest

Docker Compose (with SMTP)

services:
  paperless-backup:
    image: ghcr.io/rossberi/paperless-backup:latest
    container_name: paperless-backup
    environment:
      PAPERLESS_CONTAINER_NAME: paperless
      PAPERLESS_EXPORT_DIR: '../export'
      BACKUP_DIR: '/backups'
      EXPORT_DIR: '/export'
      BACKUP_PREFIX: 'backup'
      BACKUP_SCHEDULE: '0 2 * * *' # Optional: Daily at 02:00
      KEEP_BACKUPS: 7
      BACKUP_ON_STARTUP: False
 
      # Optional: SMTP Configuration
      # SMTP_SERVER: smtp.example.com
      # SMTP_PORT: 587
      # SMTP_USERNAME: your-email@example.com
      # SMTP_PASSWORD: your-app-password
      # SMTP_SENDER: your-email@example.com
      # SMTP_RECIPIENT: recipient@example.com
      # SMTP_SUBJECT_SUCCESS: "✅ Paperless Backup successful"
      # SMTP_SUBJECT_FAILURE: "❌ Paperless Backup failed"
      # SMTP_SECURITY: starttls
    volumes:
      - /path/to/paperless/export:/export
      - /path/to/backups:/backups
      - /var/run/docker.sock:/var/run/docker.sock

⚙️ Configuration

Required Environment Variables

Variable	Default	Description
`PAPERLESS_CONTAINER_NAME`	`paperless`	Name of the Paperless Docker container
`PAPERLESS_EXPORT_DIR`	`../export`	Export directory inside Paperless container
`BACKUP_DIR`	`/backup`	Target directory for backups
`BACKUP_PREFIX`	`backup`	Prefix of the backup files
`EXPORT_DIR`	`/export`	Local export directory
`KEEP_BACKUPS`	`7`	Number of backup versions to keep
`BACKUP_ON_STARTUP`	`False`	Run a backup on startup

Optional: SMTP Configuration

To enable email notifications, set the following variables:

Variable	Description
`SMTP_SERVER`	SMTP server address
`SMTP_PORT`	SMTP port (default: `587`)
`SMTP_USERNAME`	Username for SMTP authentication
`SMTP_PASSWORD`	Password for SMTP authentication
`SMTP_SENDER`	Sender email address
`SMTP_RECIPIENT`	Recipient email address
`SMTP_SUBJECT_SUCCESS`	Subject line for successful backup
`SMTP_SUBJECT_FAILURE`	Subject line for failed backup
`SMTP_SECURITY`	Security type: `starttls` (default), `ssl`, or `plain`

Cron Syntax

The BACKUP_SCHEDULE variable uses standard cron syntax:

╭────────────────── Minute (0 - 59)
│ ╭──────────────── Hour (0 - 23)
│ │ ╭────────────── Day of Month (1 - 31)
│ │ │ ╭──────────── Month (1 - 12)
│ │ │ │ ╭────────── Day of Week (0 - 6) (Sunday = 0)
│ │ │ │ │
│ │ │ │ │
* * * * *

Examples: