rechergg/paperless-backup repository overview

⁠paperless-backup

Open-source lightweight backup tool for paperless-ngx

paperless-backup is a lightweight backup utility for paperless-ngx environments. It automates the creation of consistent backups from a running paperless container and transfers them to remote storage, such as an SFTP server.

The tool is designed to run in containerized setups and is configured entirely through environment variables. It supports configurable backup intervals, flexible file naming, and optional cleanup of local artifacts after successful uploads.

Retention policies can be applied to control long-term storage usage. Multiple strategies are available, ranging from simple "keep last N" behavior to more advanced models like Grandfather-Father-Son (GFS), allowing a balance between short-term recovery points and long-term history.

The focus of this project is reliability, predictable behavior, and minimal operational overhead.

⁠Table of Contents

• Storage Backends⁠
• Remote Layout⁠
• Getting Started⁠
• Configuration⁠
• Retention Strategies⁠

⁠Storage Backends

⁠Remote Layout

Backups are stored in a structured directory tree on the remote:

paperless/
├── backups/
│   └── YYYY/MM/DD/
│       └── <timestamp>.tar.gz
├── metadata/
│   └── YYYY/MM/DD/
│       └── <timestamp>.tar.gz.sha256
└── latest.tar.gz

Each archive has a corresponding .sha256 sidecar written to metadata/ after a successful upload. latest.tar.gz always points to the most recent backup.

⁠Getting Started

services:
  paperless-backup:
    image: ghcr.io/rechergg/paperless-backup:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      PAPERLESS_CONTAINER: paperless-webserver
      SFTP_HOST: your-storage-box.example.com
      SFTP_USERNAME: your-username
      SFTP_KEY: your-private-key
      SFTP_PATH: paperless
      BACKUP_INTERVAL_HOURS: 6

A full docker-compose.coolify.yml is available in the repository for Coolify deployments.

⁠Configuration

All configuration is done through environment variables. The config.toml in the repository documents every available option with its default value.

⁠Retention Strategies

Configure the strategy via RETENTION_STRATEGY (default: gfs).

⁠GFS — Grandfather-Father-Son

The default strategy. Keeps backups across four tiers so you always have recent snapshots as well as long-term history.

A file is kept if it qualifies in any tier — so a weekly snapshot is never deleted just because the hourly window has passed.

⁠Simple

Keeps only the N most recent backups regardless of age.

⁠Time-based

Deletes any backup older than a configured number of days.

RETENTION_MINIMUM_KEEP prevents full deletion during extended outages — even if all backups exceed max_age_days, the most recent one is never removed.

⁠Daily

Keeps one backup per calendar day for the last N days.

⁠None

Disables cleanup entirely. All backups are kept indefinitely. Set RETENTION_STRATEGY=none — no additional variables required.