Skip to content

kyleinprogress/snapraidarr

BranchesTags

Repository files navigation

SnapRaidarr

SnapRAID automation tool designed for integration with *arr applications (Radarr, Sonarr, etc.). Provides automated SnapRAID operations with safety checks, notifications, and webhook support for seamless integration with media management applications.

Features

  • Safety Checks: Configurable thresholds for deleted files (count and percentage)
  • Multiple Webhooks: Support for multiple URLs per event (pre-run, success, failure)
  • Webhook Separation: Different webhook URLs for success vs failure scenarios
  • Email Notifications: SMTP support with success/failure options
  • Duplicate Protection: Prevents overlapping runs with lockfile mechanism
  • Logging: Rotating log files with configurable size limits
  • Docker Support: Easy deployment with Docker and docker-compose
  • Healthchecks.io Integration: Built-in support for monitoring services

Quick Start

Prerequisites

  • Docker and docker-compose installed
  • SnapRAID configuration file
  • Access to your data drives

Installation

  1. Clone the repository:
git clone https://github.com/kyleinprogress/snapraidarr.git
cd snapraidarr
  1. Run the setup script:
chmod +x scripts/setup.sh
./scripts/setup.sh
  1. Configure the application:
# Edit SnapRAID configuration
nano snapraid.conf

# Edit SnapRaidarr configuration
nano config/snapraidarr.conf
  1. Test the installation:
./scripts/run-snapraidarr.sh
  1. Set up automated runs:
# Add to crontab for nightly execution
echo "0 2 * * * cd $(pwd) && ./scripts/run-snapraidarr.sh >> logs/cron.log 2>&1" | crontab -

Configuration

Basic Configuration

The main configuration file is located at config/snapraidarr.conf:

[general]
lock_directory = /app/locks
max_runtime_hours = 12

[snapraid]
executable = /usr/local/bin/snapraid
config_file = /etc/snapraid.conf
run_scrub = true
scrub_percentage = 5
scrub_age = 10

[safety]
max_deleted_files = 50
max_deleted_percentage = 5.0

[logging]
log_file = /app/logs/snapraidarr.log
log_level = INFO
max_log_size_mb = 10
backup_count = 5

[email]
enabled = false
smtp_server = smtp.gmail.com
smtp_port = 587
use_tls = true
username = [email protected]
password = your_app_password
from_email = [email protected]
to_email = [email protected]
send_on_success = true
send_on_failure = true

[webhooks]
enabled = true
timeout = 30
pre_run_urls = http://localhost:7878/api/v3/system/shutdown?apikey=KEY1,http://localhost:8989/api/v3/system/shutdown?apikey=KEY2,https://hc-ping.com/uuid/start
post_run_success_urls = http://localhost:7878/api/v3/system/restart?apikey=KEY1,http://localhost:8989/api/v3/system/restart?apikey=KEY2,https://hc-ping.com/uuid
post_run_fail_urls = http://localhost:7878/api/v3/system/restart?apikey=KEY1,http://localhost:8989/api/v3/system/restart?apikey=KEY2,https://hc-ping.com/uuid/fail

Docker Compose Configuration

Update the docker-compose.yml file to match your system:

version: '3.8'

services:
  snapraidarr:
    build: .
    container_name: snapraidarr
    restart: unless-stopped

    volumes:
      # Mount your data drives (adjust paths as needed)
      - /mnt/disk1:/mnt/disk1:rw
      - /mnt/disk2:/mnt/disk2:rw
      - /mnt/parity1:/mnt/parity1:rw

      # Configuration, logs, and locks
      - ./config:/app/config:rw
      - ./logs:/app/logs:rw
      - ./locks:/app/locks:rw

      # SnapRAID config file
      - ./snapraid.conf:/etc/snapraid.conf:ro

    network_mode: host
    environment:
      - TZ=America/New_York

    profiles:
      - manual

Webhook Integration

Radarr/Sonarr Integration

SnapRaidarr can automatically disable imports during SnapRAID operations:

# Disable all instances before SnapRAID runs
pre_run_urls = http://radarr1:7878/api/v3/system/shutdown?apikey=KEY1,http://sonarr1:8989/api/v3/system/shutdown?apikey=KEY2

# Re-enable on success
post_run_success_urls = http://radarr1:7878/api/v3/system/restart?apikey=KEY1,http://sonarr1:8989/api/v3/system/restart?apikey=KEY2

# Re-enable on failure (ensures services restart)
post_run_fail_urls = http://radarr1:7878/api/v3/system/restart?apikey=KEY1,http://sonarr1:8989/api/v3/system/restart?apikey=KEY2

Healthchecks.io Integration

Monitor your SnapRAID runs with Healthchecks.io:

  1. Create a check at https://healthchecks.io
  2. Get your check UUID
  3. Add URLs to your configuration:
# Start monitoring
pre_run_urls = https://hc-ping.com/YOUR_UUID/start

# Signal success
post_run_success_urls = https://hc-ping.com/YOUR_UUID

# Signal failure
post_run_fail_urls = https://hc-ping.com/YOUR_UUID/fail

Usage

Manual Execution

Run SnapRaidarr manually for testing:

# Using the convenience script
./scripts/run-snapraidarr.sh

# Using docker-compose directly
docker-compose run --rm snapraidarr

# With custom config file
docker-compose run --rm snapraidarr -c /app/config/custom.conf

Automated Execution

Set up automated runs using cron:

# Edit crontab
crontab -e

# Add nightly run at 2 AM
0 2 * * * cd /path/to/snapraidarr && docker-compose run --rm snapraidarr >> logs/cron.log 2>&1

Log Monitoring

Monitor SnapRaidarr operations:

# View current logs
tail -f logs/snapraidarr.log

# View Docker logs
docker-compose logs snapraidarr

# Check for running instances
docker ps | grep snapraidarr

# Check lock status
ls -la locks/

Safety Features

Deletion Thresholds

SnapRaidarr includes configurable safety checks to prevent data loss:

  • max_deleted_files: Maximum number of deleted files before aborting
  • max_deleted_percentage: Maximum percentage of deleted files before aborting

Duplicate Run Protection

Built-in lockfile mechanism prevents overlapping runs:

  • Creates lock files with PID and timestamp
  • Automatically removes stale locks from crashed processes
  • Configurable maximum runtime before considering locks stale

Operation Sequence

  1. Pre-run webhooks: Disable *arr applications
  2. Diff operation: Check for changes and validate deletion thresholds
  3. Sync operation: Update parity information
  4. Scrub operation: Verify data integrity (optional)
  5. Post-run webhooks: Re-enable *arr applications based on success/failure

Troubleshooting

Common Issues

Permission denied errors:

# Ensure proper permissions
sudo chown -R $USER:$USER ./config ./logs ./locks
chmod 755 scripts/*.sh

Webhook timeouts:

# Test webhook connectivity
curl -X GET "http://localhost:7878/api/v3/system/status?apikey=YOUR_KEY"

Lock file issues:

# Remove stale lock manually
rm -f locks/snapraidarr.lock

Container build issues:

# Force rebuild
docker-compose build --no-cache

Debug Mode

Run with debug logging:

# Edit config/snapraidarr.conf
log_level = DEBUG

# Run manually to see detailed output
docker-compose run --rm snapraidarr

Development

Building from Source

# Build the Docker image
docker-compose build

# Run tests (if available)
docker-compose run --rm snapraidarr python -m pytest

# Access container shell for debugging
docker-compose run --rm snapraidarr bash

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

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

Support

  • Issues: Report bugs and feature requests on GitHub Issues
  • Documentation: Check the docs/ directory for detailed documentation
  • Community: Join discussions in GitHub Discussions

Acknowledgments

  • SnapRAID project for the core functionality
  • *arr application developers for the API integrations
  • Docker community for containerization best practices

About

SnapRAID automation tool designed for integration with the *arr stack

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Languages