shell/plex/README.md

# Plex Backup and Management Scripts

This directory contains all scripts and documentation related to Plex Media Server backup, restoration, validation, and management.

## Scripts Overview

### Core Backup Scripts

#### `backup-plex.sh`

**Enhanced Plex backup script with advanced features**

- **Full backup operations** with integrity verification
- **Performance monitoring** with JSON-based logging
- **WAL file handling** for SQLite databases
- **Database integrity checks** with automated repair options
- **Parallel processing** for improved performance
- **Multi-channel notifications** (console, webhook, email)
- **Comprehensive logging** with color-coded output

**Usage:**

```bash
./backup-plex.sh                    # Standard backup
./backup-plex.sh --check-integrity  # Integrity check only
./backup-plex.sh --non-interactive  # Automated mode
./backup-plex.sh --auto-repair      # Auto-repair database issues
```

#### `restore-plex.sh`

**Safe restoration script with validation**

- **Backup validation** before restoration
- **Dry-run mode** for testing
- **Current data backup** before restoration
- **Interactive backup selection**

**Usage:**

```bash
./restore-plex.sh                                        # List available backups
./restore-plex.sh plex-backup-20250125_143022.tar.gz    # Restore specific backup
./restore-plex.sh --dry-run backup-file.tar.gz          # Test restoration
```

#### `validate-plex-backups.sh`

**Backup validation and health monitoring**

- **Archive integrity checking**
- **Backup freshness validation**
- **Comprehensive reporting**
- **Automated fix suggestions**

**Usage:**

```bash
./validate-plex-backups.sh          # Validate all backups
./validate-plex-backups.sh --report # Generate detailed report
./validate-plex-backups.sh --fix    # Auto-fix issues where possible
```

### Testing and Monitoring

#### `test-plex-backup.sh`

**Comprehensive testing framework**

- **Unit tests** for core functionality
- **Integration tests** for full system testing
- **Performance benchmarks**

**Usage:**

```bash
./test-plex-backup.sh all           # Run all tests
./test-plex-backup.sh unit          # Unit tests only
./test-plex-backup.sh performance   # Performance benchmarks
```

#### `integration-test-plex.sh`

**Integration testing for Plex backup system**

- **End-to-end testing**
- **System integration validation**
- **Environment compatibility checks**

#### `monitor-plex-backup.sh`

**Real-time backup monitoring**

- **Live backup status**
- **Performance metrics**
- **Error detection and alerting**

### Utility Scripts

#### `plex.sh`

**Plex Media Server service management**

- **Service start/stop/restart**
- **Status monitoring**
- **Safe service management**

#### `plex-recent-additions.sh`

**Recent media additions reporting**

- **New content detection**
- **Addition summaries**
- **Media library analytics**

## Configuration

### Environment Variables

Key configuration parameters in `backup-plex.sh`:

```bash
# Retention settings
MAX_BACKUP_AGE_DAYS=30        # Remove backups older than 30 days
MAX_BACKUPS_TO_KEEP=10        # Keep maximum of 10 backup archives

# Directory settings
BACKUP_ROOT="/mnt/share/media/backups/plex"
LOG_ROOT="/mnt/share/media/backups/logs"

# Feature toggles
PARALLEL_VERIFICATION=true    # Enable parallel verification
PERFORMANCE_MONITORING=true  # Track performance metrics
AUTO_REPAIR=false            # Automatic database repair
```

### Backup Strategy

The enhanced backup system implements:

- **Archive-only structure**: Direct `.tar.gz` storage
- **Timestamp naming**: `plex-backup-YYYYMMDD_HHMMSS.tar.gz`
- **Automatic cleanup**: Age and count-based retention
- **Integrity validation**: Comprehensive archive verification

## Directory Structure

```
/mnt/share/media/backups/plex/
├── plex-backup-20250125_143022.tar.gz    # Latest backup
├── plex-backup-20250124_143011.tar.gz    # Previous backup
├── plex-backup-20250123_143008.tar.gz    # Older backup
└── logs/
    ├── backup_log_20250125_143022.md
    ├── plex-backup-performance.json
    └── plex-backup.json
```

## Enhanced Features

### Performance Monitoring

- **JSON performance logs**: All operations timed and logged
- **Performance reports**: Automatic generation of metrics
- **Operation tracking**: Backup, verification, service management times

### Database Management

- **Integrity checking**: Comprehensive SQLite database validation
- **Automated repair**: Optional auto-repair of corruption
- **WAL file handling**: Proper SQLite Write-Ahead Logging management

### Notification System

- **Console output**: Color-coded status messages
- **Webhook notifications**: Custom webhook URL support
- **Email notifications**: SMTP-based email alerts
- **Default webhook**: Automatic notifications to configured endpoint

### Safety Features

- **Pre-flight checks**: Disk space and system validation
- **Service management**: Safe Plex service start/stop
- **Backup verification**: Checksum and integrity validation
- **Error handling**: Comprehensive error detection and recovery

## Automation and Scheduling

### Cron Integration

Example crontab entries for automated operations:

```bash
# Daily Plex backup at 04:15
15 4 * * * /home/acedanger/shell/plex/backup-plex.sh --non-interactive --auto-repair 2>&1 | logger -t plex-backup -p user.info

# Daily validation at 07:00
0 7 * * * /home/acedanger/shell/plex/validate-plex-backups.sh --fix 2>&1 | logger -t plex-validation -p user.info
```

### Log Monitoring

Monitor backup operations with:

```bash
# Real-time monitoring
sudo journalctl -f -t plex-backup -t plex-validation

# Historical analysis
sudo journalctl --since '24 hours ago' -t plex-backup

# Performance analysis
jq '.[] | select(.operation == "backup") | .duration_seconds' logs/plex-backup-performance.json
```

## Troubleshooting

### Common Issues

1. **Database corruption**: Use `--auto-repair` flag or manual repair
2. **Insufficient disk space**: Check space requirements (2x backup size)
3. **Service management**: Ensure Plex service accessibility
4. **Archive validation**: Use validation script for integrity checks

### Debug Mode

Enable verbose logging:

```bash
# Add environment variable for debug output
PLEX_DEBUG=true ./backup-plex.sh
```

### Log Analysis

```bash
# Check backup success rate
grep "SUCCESS" logs/plex-backup-*.log | wc -l

# Analyze errors
grep "ERROR" logs/plex-backup-*.log | tail -10

# Performance trends
jq '[.[] | select(.operation == "backup") | .duration_seconds] | add/length' logs/plex-backup-performance.json
```

## Security Considerations

### File Permissions

- Backup files created with appropriate permissions
- Sensitive files maintain original ownership
- Temporary files properly cleaned up

### Access Control

- Script requires appropriate sudo permissions
- Backup locations should have restricted access
- Log files contain operational data only

### Network Security

- Webhook notifications use HTTPS when possible
- No sensitive data included in notifications
- Email notifications respect system configuration

## Documentation

### Detailed Documentation

- **[plex-backup.md](./plex-backup.md)**: Comprehensive backup script documentation
- **[plex-management.md](./plex-management.md)**: Plex management and administration guide

### Integration Notes

- All scripts follow repository coding standards
- Consistent logging and error handling
- Color-coded output for readability
- Comprehensive help systems

## Migration Notes

When migrating from legacy backup scripts:

1. **Backup current configuration**: Save any custom modifications
2. **Test new scripts**: Run with `--check-integrity` first
3. **Update automation**: Modify cron jobs to use new options
4. **Monitor performance**: Check performance logs for optimization

The enhanced scripts maintain backward compatibility while adding significant new capabilities.

---

*For additional support and advanced configuration options, refer to the detailed documentation files in this directory.*