peterwood/shell
1
0
Fork 0
mirror of https://github.com/acedanger/shell.git synced 2025-12-05 22:50:18 -08:00
Code Issues 19 Packages Projects Releases Wiki Activity

docs: Remove outdated Docker-based testing framework documentation

Browse Source
This commit is contained in:
Peter Wood
2025-05-26 08:14:33 -04:00
parent eb9bb56a5c
commit 762fa4bb9e
3 changed files with 295 additions and 486 deletions
Download Patch File Download Diff File Expand all files Collapse all files

365
docs/enhanced-plex-backup.md
View File

@@ -1,365 +0,0 @@
# Enhanced Plex Backup Script Documentation
This document provides comprehensive documentation for the enhanced `backup-plex.sh` script. This advanced backup solution includes performance monitoring, parallel processing, intelligent notifications, WAL file handling, and automated testing capabilities.
## Script Overview
The enhanced script performs the following advanced tasks:
1. **Performance Monitoring**: Tracks backup operations with JSON-based performance logging
2. **Intelligent Backup Detection**: Only backs up files that have changed since last backup
3. **WAL File Handling**: Properly handles SQLite Write-Ahead Logging files
4. **Database Integrity Verification**: Comprehensive integrity checks with automated repair options
5. **Parallel Processing**: Concurrent verification for improved performance
6. **Multi-Channel Notifications**: Console, webhook, and email notification support
7. **Checksum Caching**: Intelligent caching to avoid recalculating unchanged file checksums
8. **Enhanced Service Management**: Safe Plex service management with progress indicators
9. **Comprehensive Logging**: Detailed logs with color-coded output and timestamps
10. **Automated Cleanup**: Configurable retention policies for old backups
## Enhanced Features
### Performance Tracking
- **JSON Performance Logs**: All operations are timed and logged to `logs/plex-backup-performance.json`
- **Performance Reports**: Automatic generation of average performance metrics
- **Operation Monitoring**: Tracks backup, verification, service management, and overall script execution times
### Notification System
The script supports multiple notification channels:
#### Console Notifications
- Color-coded status messages (Success: Green, Error: Red, Warning: Yellow, Info: Blue)
- Timestamped log entries with clear formatting
#### Webhook Notifications
```bash
./backup-plex.sh --webhook=https://your-webhook-url.com/endpoint
```
Sends JSON payloads with backup status, hostname, and timestamps.
#### Email Notifications
```bash
./backup-plex.sh --email=admin@example.com
```
Requires `sendmail` to be configured on the system.
### WAL File Management
The script now properly handles SQLite Write-Ahead Logging files:
- **Automatic Detection**: Identifies and backs up `.db-wal` and `.db-shm` files when present
- **WAL Checkpointing**: Performs `PRAGMA wal_checkpoint(FULL)` before integrity checks
- **Safe Backup**: Ensures WAL files are properly backed up alongside main database files
### Database Integrity & Repair
Enhanced database management features:
- **Pre-backup Integrity Checks**: Verifies database health before backup operations
- **Automated Repair**: Optional automatic repair of corrupted databases using advanced techniques
- **Interactive Repair Mode**: Prompts for repair decisions when issues are detected
- **Post-repair Verification**: Re-checks integrity after repair operations
### Parallel Processing
- **Concurrent Verification**: Parallel backup verification for improved performance
- **Fallback Safety**: Automatically falls back to sequential processing if parallel mode fails
- **Configurable**: Can be disabled with `--no-parallel` for maximum safety
## Command Line Options
```bash
Usage: ./backup-plex.sh [OPTIONS]
Options:
--auto-repair Automatically attempt to repair corrupted databases
--check-integrity Only check database integrity, don't backup
--non-interactive Run in non-interactive mode (for automation)
--no-parallel Disable parallel verification (slower but safer)
--no-performance Disable performance monitoring
--webhook=URL Send notifications to webhook URL
--email=ADDRESS Send notifications to email address
-h, --help Show help message
```
## Configuration Files
### Performance Log Format
The performance log (`logs/plex-backup-performance.json`) contains entries like:
```json
[
{
"operation": "backup",
"duration_seconds": 45.3,
"timestamp": "2025-05-25T19:45:23-05:00"
},
{
"operation": "verification",
"duration_seconds": 12.8,
"timestamp": "2025-05-25T19:46:08-05:00"
}
]
```
### Backup Tracking Log
The backup tracking log (`logs/plex-backup.json`) tracks last backup times:
```json
{
"/var/lib/plexmediaserver/.../com.plexapp.plugins.library.db": 1732567523,
"/var/lib/plexmediaserver/.../Preferences.xml": 1732567523
}
```
## Usage Examples
### Basic Backup
```bash
./backup-plex.sh
```
Performs a standard backup with all enhanced features enabled.
### Integrity Check Only
```bash
./backup-plex.sh --check-integrity
```
Only checks database integrity without performing backup.
### Automated Backup with Notifications
```bash
./backup-plex.sh --non-interactive --auto-repair --webhook=https://notify.example.com/backup
```
Runs in automated mode with auto-repair and webhook notifications.
### Performance-Optimized Backup
```bash
./backup-plex.sh --no-parallel --no-performance
```
Runs with parallel processing and performance monitoring disabled for maximum compatibility.
## Automation and Scheduling
### Cron Job Setup
For daily automated backups at 2 AM:
```bash
# Edit crontab
crontab -e
# Add this line for daily backup
0 2 * * * /home/acedanger/shell/backup-plex.sh --non-interactive --auto-repair --email=admin@example.com 2>&1 | logger -t plex-backup
```
### Systemd Service
Create a systemd service for more control:
```ini
[Unit]
Description=Plex Backup Service
After=network.target
[Service]
Type=oneshot
User=root
ExecStart=/home/acedanger/shell/backup-plex.sh --non-interactive --auto-repair
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
### Systemd Timer
Create a timer for regular execution:
```ini
[Unit]
Description=Daily Plex Backup
Requires=plex-backup.service
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target
```
## Monitoring and Alerts
### Performance Monitoring
The script automatically tracks:
- Backup operation duration
- Verification times
- Service start/stop times
- Overall script execution time
### Health Checks
Regular health monitoring can be implemented by checking:
```bash
# Check last backup success
jq -r '.[-1] | select(.operation == "total_script") | .timestamp' logs/plex-backup-performance.json
# Check average backup performance
jq '[.[] | select(.operation == "backup") | .duration_seconds] | add/length' logs/plex-backup-performance.json
```
## Troubleshooting
### Common Issues
1. **Permission Denied Errors**
- Ensure script runs with appropriate sudo permissions
- Check Plex file ownership and permissions
2. **WAL File Warnings**
- Now handled automatically by the enhanced script
- WAL checkpointing ensures data consistency
3. **Performance Issues**
- Use `--no-parallel` if concurrent operations cause problems
- Monitor performance logs for bottlenecks
4. **Notification Failures**
- Verify webhook URLs are accessible
- Check sendmail configuration for email notifications
### Debug Mode
Enable verbose logging by modifying the script or using:
```bash
bash -x ./backup-plex.sh --check-integrity
```
## Testing Framework
The script includes a comprehensive testing framework (`test-plex-backup.sh`):
### Running Tests
```bash
# Run all tests
./test-plex-backup.sh all
# Run only unit tests
./test-plex-backup.sh unit
# Run performance benchmarks
./test-plex-backup.sh performance
```
### Test Categories
- **Unit Tests**: Core functionality verification
- **Integration Tests**: Full system testing (requires Plex installation)
- **Performance Tests**: Benchmarking and performance validation
## Security Considerations
### File Permissions
- Backup files are created with appropriate permissions
- Sensitive files maintain original ownership and permissions
- Temporary files are properly cleaned up
### Network Security
- Webhook notifications use HTTPS when possible
- Email notifications respect system sendmail configuration
- No sensitive data is included in notifications
### Access Control
- Script requires appropriate sudo permissions
- Backup locations should have restricted access
- Log files contain operational data, not sensitive information
## Backup Strategy
The enhanced script implements a robust backup strategy with a streamlined tar.gz-only structure:
### Archive-Only Directory Structure
The new backup system eliminates intermediate dated directories and stores only compressed archives:
```bash
/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
```
### Archive Naming Convention
Backup files follow the pattern: `plex-backup-YYYYMMDD_HHMMSS.tar.gz`
- **YYYYMMDD**: Date of backup (e.g., 20250125)
- **HHMMSS**: Time of backup (e.g., 143022)
- **tar.gz**: Compressed archive format
### Key Improvements
1. **Direct Archive Creation**: No intermediate directories required
2. **Efficient Storage**: Only compressed files stored permanently
3. **Easy Identification**: Timestamp-based naming for sorting
4. **Legacy Cleanup**: Automatic removal of old dated directories
5. **Archive Validation**: Integrity checking of compressed files
### 3-2-1 Backup Rule
1. **3 Copies**: Original data + local backup + compressed archive
2. **2 Different Media**: Local disk + network storage capability
3. **1 Offsite**: Ready for remote synchronization
### Retention Policy
- Configurable maximum backup age (default: 30 days)
- Configurable maximum backup count (default: 10 backups)
- Automatic cleanup of old backups
### Verification Strategy
- Checksum verification for all backed up files
- Database integrity checks before and after operations
- Optional parallel verification for improved performance
## Migration from Legacy Script
To migrate from the original backup script:
1. **Backup Current Configuration**: Save any custom modifications
2. **Test New Script**: Run with `--check-integrity` first
3. **Update Automation**: Modify cron jobs to use new options
4. **Monitor Performance**: Check performance logs for optimization opportunities
The enhanced script maintains backward compatibility while adding significant new capabilities.

333
docs/plex-backup.md
View File

@@ -73,7 +73,7 @@ Enhanced database management features:
- **Fallback Safety**: Automatically falls back to sequential processing if parallel mode fails
- **Configurable**: Can be disabled with `--no-parallel` for maximum safety
### Command Line Options
## Command Line Options
```bash
Usage: ./backup-plex.sh [OPTIONS]
@@ -89,7 +89,9 @@ Options:
-h, --help Show help message
```
## Detailed Steps
## Detailed Backup Process Steps
The backup script follows these detailed steps to ensure data integrity and reliability:
### 1. Create Log Directory
@@ -107,22 +109,7 @@ LOG_FILE="/mnt/share/media/backups/logs/backup_log_$(date +%Y%m%d_%H%M%S).md"
This line defines the log file path, including the current date and time in the filename to ensure uniqueness.
### 3. Define Log File Details Function
```bash
log_file_details() {
local src=$1
local dest=$2
local size=$(du -sh "$dest" | cut -f1)
echo "Source: $src" >> "$LOG_FILE"
echo "Destination: $dest" >> "$LOG_FILE"
echo "Size: $size" >> "$LOG_FILE"
}
```
This function logs the details of the copied files, including the source, destination, and size.
### 4. Stop Plex Media Server Service
### 3. Stop Plex Media Server Service
```bash
if systemctl is-active --quiet plexmediaserver.service; then
@@ -132,25 +119,20 @@ fi
This block checks if the Plex Media Server service is running. If it is, the script stops the service using a custom script (`plex.sh`).
### 5. Backup Plex Database Files and Preferences
### 4. Backup Plex Database Files and Preferences
The enhanced backup system now creates compressed archives directly, eliminating intermediate directories:
The enhanced backup system creates compressed archives directly, eliminating intermediate directories:
```bash
# Files are copied to temporary staging area for verification
cp "/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-in Support/Databases/com.plexapp.plugins.library.db" "$BACKUP_PATH/"
log_file_details "com.plexapp.plugins.library.db" "$BACKUP_PATH/"
cp "/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-in Support/Databases/com.plexapp.plugins.library.blobs.db" "$BACKUP_PATH/"
log_file_details "com.plexapp.plugins.library.blobs.db" "$BACKUP_PATH/"
cp "/var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Preferences.xml" "$BACKUP_PATH/"
log_file_details "Preferences.xml" "$BACKUP_PATH/"
```
These commands copy the Plex database files and preferences directly to the backup root directory. Each file copy operation includes integrity verification and checksum validation.
### 6. Create Compressed Archive
### 5. Create Compressed Archive
```bash
# Create archive directly with timestamp naming convention
@@ -158,15 +140,14 @@ final_archive="${BACKUP_ROOT}/plex-backup-$(date '+%Y%m%d_%H%M%S').tar.gz"
tar -czf "$final_archive" -C "$temp_staging_dir" .
```
The system now creates compressed archives directly using a timestamp-based naming convention (`plex-backup-YYYYMMDD_HHMMSS.tar.gz`), eliminating the need for intermediate dated directories.
The system creates compressed archives directly using a timestamp-based naming convention (`plex-backup-YYYYMMDD_HHMMSS.tar.gz`), eliminating the need for intermediate dated directories.
### 7. Archive Validation and Cleanup
### 6. Archive Validation and Cleanup
```bash
# Validate archive integrity
if tar -tzf "$final_archive" >/dev/null 2>&1; then
log_success "Archive created and validated: $(basename "$final_archive")"
# Clean up temporary staging files
rm -rf "$temp_staging_dir"
else
log_error "Archive validation failed"
@@ -176,7 +157,7 @@ fi
The system validates the created archive and removes temporary staging files, ensuring only valid compressed backups are retained in the backup root directory.
### 8. Send Notification
### 7. Send Notification
```bash
curl \
@@ -185,9 +166,9 @@ curl \
https://notify.peterwood.rocks/lab || { echo "Failed to send notification"; exit 1; }
```
This command sends a notification upon completion of the backup process, indicating the compressed archive has been created. If the notification fails, the script exits with an error message.
This command sends a notification upon completion of the backup process, indicating the compressed archive has been created.
### 9. Restart Plex Media Server Service
### 8. Restart Plex Media Server Service
```bash
if systemctl is-enabled --quiet plexmediaserver.service; then
@@ -197,7 +178,7 @@ fi
This block checks if the Plex Media Server service is enabled. If it is, the script restarts the service using a custom script (`plex.sh`).
### 10. Legacy Cleanup
### 9. Legacy Cleanup
```bash
# Clean up any remaining dated directories from old backup structure
@@ -206,6 +187,240 @@ find "${BACKUP_ROOT}" -maxdepth 1 -type d -name "????????" -exec rm -rf {} \; 2>
The enhanced system includes cleanup of legacy dated directories from previous backup structure versions, ensuring a clean tar.gz-only backup directory.
## Configuration Files
### Performance Log Format
The performance log (`logs/plex-backup-performance.json`) contains entries like:
```json
[
{
"operation": "backup",
"duration_seconds": 45.3,
"timestamp": "2025-05-25T19:45:23-05:00"
},
{
"operation": "verification",
"duration_seconds": 12.8,
"timestamp": "2025-05-25T19:46:08-05:00"
}
]
```
### Backup Tracking Log
The backup tracking log (`logs/plex-backup.json`) tracks last backup times:
```json
{
"/var/lib/plexmediaserver/.../com.plexapp.plugins.library.db": 1732567523,
"/var/lib/plexmediaserver/.../Preferences.xml": 1732567523
}
```
## Usage Examples
### Basic Backup
```bash
./backup-plex.sh
```
Performs a standard backup with all enhanced features enabled.
### Integrity Check Only
```bash
./backup-plex.sh --check-integrity
```
Only checks database integrity without performing backup.
### Automated Backup with Notifications
```bash
./backup-plex.sh --non-interactive --auto-repair --webhook=https://notify.example.com/backup
```
Runs in automated mode with auto-repair and webhook notifications.
### Performance-Optimized Backup
```bash
./backup-plex.sh --no-parallel --no-performance
```
Runs with parallel processing and performance monitoring disabled for maximum compatibility.
## Automation and Scheduling
### Cron Job Setup
For daily automated backups at 2 AM:
```bash
# Edit crontab
crontab -e
# Add this line for daily backup
0 2 * * * /home/acedanger/shell/backup-plex.sh --non-interactive --auto-repair --email=admin@example.com 2>&1 | logger -t plex-backup
```
### Systemd Service
Create a systemd service for more control:
```ini
[Unit]
Description=Plex Backup Service
After=network.target
[Service]
Type=oneshot
User=root
ExecStart=/home/acedanger/shell/backup-plex.sh --non-interactive --auto-repair
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
### Systemd Timer
Create a timer for regular execution:
```ini
[Unit]
Description=Daily Plex Backup
Requires=plex-backup.service
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target
```
## Monitoring and Alerts
### Performance Monitoring
The script automatically tracks:
- Backup operation duration
- Verification times
- Service start/stop times
- Overall script execution time
### Health Checks
Regular health monitoring can be implemented by checking:
```bash
# Check last backup success
jq -r '.[-1] | select(.operation == "total_script") | .timestamp' logs/plex-backup-performance.json
# Check average backup performance
jq '[.[] | select(.operation == "backup") | .duration_seconds] | add/length' logs/plex-backup-performance.json
```
## Troubleshooting
### Common Issues
1. **Permission Denied Errors**
- Ensure script runs with appropriate sudo permissions
- Check Plex file ownership and permissions
2. **WAL File Warnings**
- Now handled automatically by the enhanced script
- WAL checkpointing ensures data consistency
3. **Performance Issues**
- Use `--no-parallel` if concurrent operations cause problems
- Monitor performance logs for bottlenecks
4. **Notification Failures**
- Verify webhook URLs are accessible
- Check sendmail configuration for email notifications
### Debug Mode
Enable verbose logging by modifying the script or using:
```bash
bash -x ./backup-plex.sh --check-integrity
```
## Testing Framework
The script includes a comprehensive testing framework (`test-plex-backup.sh`):
### Running Tests
```bash
# Run all tests
./test-plex-backup.sh all
# Run only unit tests
./test-plex-backup.sh unit
# Run performance benchmarks
./test-plex-backup.sh performance
```
### Test Categories
- **Unit Tests**: Core functionality verification
- **Integration Tests**: Full system testing (requires Plex installation)
- **Performance Tests**: Benchmarking and performance validation
## Security Considerations
### File Permissions
- Backup files are created with appropriate permissions
- Sensitive files maintain original ownership and permissions
- Temporary files are properly cleaned up
### Network Security
- Webhook notifications use HTTPS when possible
- Email notifications respect system sendmail configuration
- No sensitive data is included in notifications
### Access Control
- Script requires appropriate sudo permissions
- Backup locations should have restricted access
- Log files contain operational data, not sensitive information
## Backup Strategy
The enhanced script implements a robust backup strategy with a streamlined tar.gz-only structure:
### Archive-Only Directory Structure
The new backup system eliminates intermediate dated directories and stores only compressed archives:
```bash
/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
```
### Archive Naming Convention
Backup files follow the naming convention `plex-backup-YYYYMMDD_HHMMSS.tar.gz` for easy identification and sorting.
## Important Information
- Ensure that the [`plex.sh`](https://github.com/acedanger/shell/blob/main/plex.sh) script is available and executable. This script is used to stop and start the Plex Media Server service.
@@ -221,12 +436,54 @@ The enhanced system includes cleanup of legacy dated directories from previous b
```
/mnt/share/media/backups/plex/
├── plex-backup-20250125_143022.tar.gz
├── plex-backup-20250124_143011.tar.gz
├── plex-backup-20250123_143008.tar.gz
├── 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-performance.json
└── plex-backup.json
```
By following this documentation, you should be able to understand and use the enhanced `backup-plex.sh` script effectively with its new streamlined tar.gz-only structure.
Backup files follow the pattern: `plex-backup-YYYYMMDD_HHMMSS.tar.gz`
- **YYYYMMDD**: Date of backup (e.g., 20250125)
- **HHMMSS**: Time of backup (e.g., 143022)
- **tar.gz**: Compressed archive format
### Key Improvements
1. **Direct Archive Creation**: No intermediate directories required
2. **Efficient Storage**: Only compressed files stored permanently
3. **Easy Identification**: Timestamp-based naming for sorting
4. **Legacy Cleanup**: Automatic removal of old dated directories
5. **Archive Validation**: Integrity checking of compressed files
### 3-2-1 Backup Rule
1. **3 Copies**: Original data + local backup + compressed archive
2. **2 Different Media**: Local disk + network storage capability
3. **1 Offsite**: Ready for remote synchronization
### Retention Policy
- Configurable maximum backup age (default: 30 days)
- Configurable maximum backup count (default: 10 backups)
- Automatic cleanup of old backups
### Verification Strategy
- Checksum verification for all backed up files
- Database integrity checks before and after operations
- Optional parallel verification for improved performance
## Migration from Legacy Script
To migrate from the original backup script:
1. **Backup Current Configuration**: Save any custom modifications
2. **Test New Script**: Run with `--check-integrity` first
3. **Update Automation**: Modify cron jobs to use new options
4. **Monitor Performance**: Check performance logs for optimization opportunities
The enhanced script maintains backward compatibility while adding significant new capabilities.

83
docs/testing-fixes.md
View File

@@ -1,83 +0,0 @@
# Docker-based Testing Framework Improvements
This document outlines the improvements made to the Docker-based testing framework for validating shell scripts and dotfiles across different environments.
## Issues Fixed
### 1. `local` Keyword Usage Outside Function
Fixed a syntax error where the `local` keyword was used outside of a function context:
```bash
# Before (incorrect):
for pkg in $packages; do
local actual_pkg=$(get_package_name "$pkg")
# ...
done
# After (correct):
for pkg in $packages; do
actual_pkg=$(get_package_name "$pkg")
# ...
done
```
### 2. Log Directory Handling
Enhanced log directory handling to ensure proper permissions and fallback mechanisms:
- Added better error handling for log directory creation and permissions
- Added validation to verify write permissions before proceeding
- Implemented fallback to /tmp if host volume mounting fails
- Added debugging information when log operations fail
### 3. Package Verification
Improved package detection, especially for packages like `cowsay` and `lolcat` that are typically installed in `/usr/games/`:
- Enhanced `test_package()` function to check in common alternate locations
- Added specific handling for packages that may be installed with different paths
- Added detailed debugging output for problematic packages
### 4. Docker Container Configuration
Improved the Docker container configuration for more reliable testing:
- Added proper volume mounting with explicit read/write permissions
- Added timestamp consistency between host and container
- Added container type labels to log files for better tracking
- Enhanced error detection for volume mounting issues
## Implementation Details
### 1. Enhanced Logging System
- Timestamps are now synchronized between host and container
- Log file names include container type (ubuntu/debian) for clarity
- Added validation to confirm logs are properly saved to host
### 2. Container Environment Setup
- Improved `startup.sh` with better diagnostics before running tests
- Added permissions verification for mounted volumes
- Added write tests to confirm permissions are correctly set
### 3. Test Framework Improvements
- Improved error handling for better diagnostics
- Enhanced reporting for package detection issues
- Better isolation between test iterations
## Running Tests
To run tests with the improved framework:
```bash
# Test in Ubuntu container
./run-docker-tests.sh ubuntu
# Test in Debian container
./run-docker-tests.sh debian
```
The logs will be saved in the `./logs` directory with filenames that include the timestamp and container type.