shell/README.md

# Shell Scripts and Dotfiles Repository

This repository contains various shell scripts for managing media-related tasks and dotfiles for system configuration.

## Available Scripts

- [Backup Media Script](docs/backup-media.md): Documentation for the `backup-media.sh` script.
- `plex.sh`: Script to manage the Plex Media Server (start, stop, restart, status).
- `backup-plex.sh`: Enhanced Plex backup script with integrity verification, incremental backups, and advanced features.
- `restore-plex.sh`: Script to restore Plex data from backups with safety checks.
- `validate-plex-backups.sh`: Script to validate backup integrity and monitor backup health.
- `folder-metrics.sh`: Script to calculate disk usage and file count for a directory and its subdirectories.

## Enhanced Plex Backup System

This repository includes an enhanced backup system for Plex Media Server with multiple components:

### Scripts

- **`backup-plex.sh`**: Advanced backup script with integrity verification, incremental backups, and automatic cleanup
- **`restore-plex.sh`**: Safe restoration script with dry-run mode and current data backup
- **`validate-plex-backups.sh`**: Backup validation and health monitoring script

### Key Features

- **Incremental backups**: Only backs up files that have changed since last backup
- **File integrity verification**: Uses MD5 checksums to verify backup integrity
- **Automatic cleanup**: Configurable retention policies for old backups
- **Disk space monitoring**: Checks available space before starting backup
- **Safe restoration**: Backs up current data before restoring from backup
- **Comprehensive logging**: Detailed logs with color-coded output
- **Service management**: Safely stops/starts Plex during backup operations

### Usage Examples

#### Enhanced Backup Script

```bash
# Run the enhanced backup (recommended)
./backup-plex.sh
```

#### Backup Validation

```bash
# Validate all backups and generate report
./validate-plex-backups.sh --report

# Validate backups and attempt to fix common issues
./validate-plex-backups.sh --fix

# Quick validation check
./validate-plex-backups.sh
```

#### Restore from Backup

```bash
# List available backups
./restore-plex.sh

# Test restore without making changes (dry run)
./restore-plex.sh 20250125 --dry-run

# Actually restore from a specific backup
./restore-plex.sh 20250125
```

### Automation Examples

#### Daily Backup with Validation

```bash
# Add to crontab for daily backup at 3 AM
0 3 * * * /home/acedanger/shell/backup-plex.sh

# Add daily validation at 7 AM
0 7 * * * /home/acedanger/shell/validate-plex-backups.sh --fix
```

#### Weekly Full Validation Report

```bash
# Generate detailed weekly report (Sundays at 8 AM)
0 8 * * 0 /home/acedanger/shell/validate-plex-backups.sh --report
```

### Configuration

The enhanced backup script includes configurable parameters at the top of the file:

- `MAX_BACKUP_AGE_DAYS=30`: Remove backups older than 30 days
- `MAX_BACKUPS_TO_KEEP=10`: Keep maximum of 10 backup sets
- `BACKUP_ROOT`: Location for backup storage
- `LOG_ROOT`: Location for backup logs

### Backup Strategy

The system implements a robust 3-2-1 backup strategy:

1. **3 copies**: Original data + local backup + compressed archive
2. **2 different media**: Local disk + network storage
3. **1 offsite**: Consider syncing to remote location

For offsite backup, add to cron:

```bash
# Sync backups to remote server daily at 6 AM
0 6 * * * rsync -av /mnt/share/media/backups/plex/ user@remote-server:/backups/plex/
```

## Documentation

- [Plex Backup Script Documentation](./docs/plex-backup.md): Detailed documentation for the `backup-plex.sh` script.
- [Plex Management Script Documentation](./docs/plex-management.md): Detailed documentation for the `plex.sh` script.
- [Folder Metrics Script Documentation](./docs/folder-metrics.md): Detailed documentation for the `folder-metrics.sh` script.
- [Testing Framework Documentation](./docs/testing.md): Detailed documentation for the Docker-based testing system.

## Dotfiles

The repository includes dotfiles for system configuration in the `dotfiles` directory. These can be automatically set up using the bootstrap script:

```bash
curl -fsSL https://raw.githubusercontent.com/acedanger/shell/main/bootstrap.sh | bash
```

For more information about the dotfiles, see [Dotfiles README](./dotfiles/README.md).

## Testing

This repository includes Docker-based testing to validate the setup process across different environments:

- **test-setup.sh**: Script that validates the bootstrap and setup process
- **run-docker-tests.sh**: Runner script that executes tests in Docker containers
- **Dockerfile**: Defines test environments (Ubuntu, Debian)

### Running Tests

Test your setup in isolated Docker containers with:

```bash
# Test in Ubuntu container
./run-docker-tests.sh ubuntu

# Test in Debian container
./run-docker-tests.sh debian

# Run full bootstrap test in Ubuntu
./run-docker-tests.sh full-ubuntu

# Run full bootstrap test in Debian
./run-docker-tests.sh full-debian

# Test in both Ubuntu and Debian
./run-docker-tests.sh all
```

#### When to Use Each Testing Option

- **Use `./run-docker-tests.sh ubuntu` or `./run-docker-tests.sh debian`** when you want to:
  - Quickly validate if packages in packages.list are available and installed
  - Test if your test-setup.sh script is working correctly
  - Check for issues with specific components without performing a full setup

- **Use `./run-docker-tests.sh full-ubuntu` or `./run-docker-tests.sh full-debian`** when you want to:
  - Test the complete bootstrap installation process end-to-end
  - Validate that all installation steps work correctly on a fresh system
  - Simulate what users will experience when running the bootstrap script

- **Use `./run-docker-tests.sh all`** when you want to:
  - Ensure your test-setup.sh works across both Ubuntu and Debian
  - Run comprehensive checks before committing changes

The test environment checks:

- Package availability and installation
- Core components (git, curl, wget, etc.)
- Additional packages from `setup/packages.list`
- Oh My Zsh and plugin installation
- Dotfile symlinks

Tests will continue even when some packages fail to install, reporting all issues in a comprehensive summary.

## plex.sh

This script is used to manage the Plex Media Server service on a systemd-based Linux distribution. It provides the following functionalities:

- **start**: Starts the Plex Media Server.
- **stop**: Stops the Plex Media Server.
- **restart**: Restarts the Plex Media Server.
- **status**: Displays the current status of the Plex Media Server.

## Usage

Note that these commands will run as `root`.

```shell
./shell/plex.sh {start|stop|restart|status}
```