restic-backup 1.0.0

A simple, configuration-driven backup tool powered by Restic

restic-backup

A simple, configuration-driven backup tool powered by Restic. Manage multiple backup projects with a single YAML configuration file.

Features

• 📝 Simple Configuration - Define all backup jobs in one YAML file
• 🚀 Snapshot-based Backups - Built on Restic's efficient incremental backup system
• 🗄️ Automatic Retention - Configurable retention policies (daily/weekly/monthly)
• 🔒 Encryption - All backups are encrypted at rest
• 🎯 Selective Exclusions - Flexible exclude patterns per project
• 🐳 Docker Support - Run as a container or use Docker Compose

Requirements

• Python 3.10+
• Restic 0.14+
• PyYAML

Installation

From PyPI (recommended)

pip install restic-backup

From Source

git clone https://github.com/beyond-infra/restic-backup.git
cd restic-backup
pip install -e .

Using Docker

docker pull ghcr.io/beyond-infra/restic-backup:latest

Quick Start

1. Install Restic

# Ubuntu/Debian
apt-get install restic

# macOS
brew install restic

# Or download from https://github.com/restic/restic/releases

2. Create Configuration

Create /etc/restic-backup/config.yaml:

repository: /var/backups/restic

retention:
  daily: 7
  weekly: 4
  monthly: 3

projects:
  my-data:
    source: /data/my-project
    exclude:
      - cache
      - "*.log"

3. Set Password

Create /etc/restic-backup/restic.env:

export RESTIC_PASSWORD="your-strong-password-here"

4. Run Backup

restic-backup backup

Configuration

Full Configuration Example

repository: /var/backups/restic

retention:
  daily: 7      # Keep 7 daily snapshots
  weekly: 4     # Keep 4 weekly snapshots
  monthly: 3    # Keep 3 monthly snapshots

projects:
  # Project 1: Immich photos
  immich:
    source: /data/immich
    exclude:
      - cache
      - library/thumbs
      - library/upload
      - postgres
      - "**/.DS_Store"

  # Project 2: Nextcloud
  nextcloud:
    source: /data/nextcloud
    exclude:
      - data/*/cache

Configuration Options

Option	Required	Description
repository	Yes	Base directory for all backup repositories
retention.daily	Yes	Number of daily snapshots to keep
retention.weekly	Yes	Number of weekly snapshots to keep
retention.monthly	Yes	Number of monthly snapshots to keep
projects.<name>.source	Yes	Source directory to backup
projects.<name>.exclude	No	List of exclusion patterns

Usage

# List configured projects
restic-backup list

# Backup all projects
restic-backup backup

# Backup specific project only
restic-backup backup immich

# Check backup status
restic-backup status

# Restore from backup
restic-backup restore immich /tmp/restore

# Restore specific snapshot
restic-backup restore immich /tmp/restore abc123de

Docker Usage

Using Docker Compose

Create docker-compose.yaml:

services:
  backup:
    image: ghcr.io/beyond-infra/restic-backup:latest
    volumes:
      - ./config.yaml:/etc/restic-backup/config.yaml:ro
      - ./restic.env:/etc/restic-backup/restic.env:ro
      - /data:/data:ro
      - /var/backups:/var/backups
    command: backup

Run:

docker compose run --rm backup

Manual Docker Run

docker run --rm \
  -v /etc/restic-backup/config.yaml:/etc/restic-backup/config.yaml:ro \
  -v /etc/restic-backup/restic.env:/etc/restic-backup/restic.env:ro \
  -v /data:/data:ro \
  -v /var/backups:/var/backups \
  ghcr.io/beyond-infra/restic-backup:latest \
  backup

Automation

Cron

# Edit crontab
crontab -e

# Daily at 2 AM
0 2 * * * restic-backup backup >> /var/log/restic-backup.log 2>&1

Systemd Timer

See examples/systemd/ directory for service and timer files.

Remote Storage

restic-backup supports all Restic storage backends. Set in restic.env:

# S3
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export RESTIC_REPOSITORY="s3:s3.amazonaws.com/bucket-name"

# SFTP
export RESTIC_REPOSITORY="sftp:user@host:/backups"

# B2
export B2_ACCOUNT_ID="..."
export B2_ACCOUNT_KEY="..."
export RESTIC_REPOSITORY="b2:bucket-name"

Development

Setup Development Environment

git clone https://github.com/beyond-infra/restic-backup.git
cd restic-backup
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

Run Tests

pytest

Code Style

ruff check .
ruff format .

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Restic - The backup program that powers this tool
• Inspired by the need for simple, configuration-driven backup management