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

feat: Update README for Backup File Browser TUI and remove demo script

Browse Source
This commit is contained in:
Peter Wood
2025-06-01 17:32:32 -04:00
parent 209b855977
commit 5b249c89bd
3 changed files with 122 additions and 218 deletions
Download Patch File Download Diff File Expand all files Collapse all files

258
tui/README.md
View File

@@ -1,8 +1,10 @@
# 🔧 Enhanced Backup Manager TUI
# 📁 Backup File Browser TUI
A modern, interactive Terminal User Interface (TUI) for## ⌨️ Enhanced Key Bindings
A modern, interactive Terminal User Interface (TUI) for browsing and viewing backup files and logs in your shell environment. Built with Go and Charm's Bubble Tea framework for a delightful file exploration experience. This TUI provides read-only access to your backup infrastructure, allowing you to explore backup directories, view file details, and browse operation logs without modifying any files.
### Navigation & Control
## ⌨️ Key Bindings
### Navigation & File Browsing
| Key | Action | Description |
|-----|--------|-------------|
@@ -11,87 +13,69 @@ A modern, interactive Terminal User Interface (TUI) for## ⌨️ Enhanced Key Bi
| `←/h` | Move left (panel navigation) | Switch to service list panel |
| `→/l` | Move right (panel navigation) | Switch to output panel |
| `Tab` | Switch between panels | Toggle between service list and output |
| `Enter/Space` | Execute selected backup | Start the selected backup operation |
| `Enter` | Browse selected directory | View backup files and details |
### View Management
| Key | Action | Description |
|-----|--------|-------------|
| `v` | View backup logs | Switch to logs view with real-time updates |
| `s` | View backup status | Display comprehensive status dashboard |
| `c` | View configuration | Show system and service configuration |
| `r` | Refresh status and logs | Reload all status information |
| `v` | View backup logs | Switch to logs view |
| `s` | View backup status | Display backup file status information |
| `f` | View configuration | Show system and service configuration |
| `r` | Refresh current view | Reload directory and status information |
| `Esc` | Return to main view | Go back to main backup selection |
### Process Control
### Interface Control
| Key | Action | Description |
|-----|--------|-------------|
| `x` | Stop running backup | Gracefully cancel active backup process |
| `Space` | Clear output panel | Clear the output display area |
| `c` | Clear output panel | Clear the output display area |
| `?` | Toggle help | Show/hide comprehensive help information |
| `q/Ctrl+C` | Quit application | Exit the TUI application |
### Advanced Features
## 🚀 Features
| Key | Action | Description |
|-----|--------|-------------|
| `f` | View configuration | Detailed system and service information |
| `p` | Progress details | Show detailed progress metrics |
| `l` | Live logs | Real-time log streaming display |p operations in your shell environment. Built with Go and Charm's Bubble Tea framework with advanced real-time features.
### 📁 File Browser Interface
## 🚀 Enhanced Features
- **Directory Navigation**: Browse backup directories for different services
- **File Details**: View file sizes, modification dates, and backup types
- **Service Organization**: Organized by backup service (Plex, Immich, Media services, etc.)
- **Log File Viewing**: Browse and read backup operation logs
### 📊 Real-time Progress Tracking
### 📊 Information Display
- **Visual Progress Bars**: Live progress indicators with percentage display
- **ETA Calculations**: Intelligent time estimation based on current progress
- **Output Streaming**: Real-time display of backup command output
- **Performance Metrics**: Elapsed time tracking and transfer statistics
- **Backup Statistics**: View file counts, total sizes, and backup ages
- **Status Information**: Display backup directory health and availability
- **Configuration Details**: Show system and service configuration information
- **File Metadata**: Display compressed file status and service associations
### 🎛️ Advanced Process Management
### 🖥️ User Interface
- **Context Cancellation**: Graceful backup cancellation with context support
- **Process Monitoring**: Track and control multiple simultaneous backups
- **Resource Management**: Memory-safe output handling with line limits
- **Thread Safety**: Concurrent operation support with proper synchronization
### 🖥️ Enhanced User Interface
- **Dual-panel System**: Service list and live output viewer
- **Multiple View Modes**: Main, logs, status, and configuration views
- **Dual-panel System**: Service list and detailed information viewer
- **Multiple View Modes**: Main browser, logs viewer, status, and configuration views
- **Tab Navigation**: Switch between panels with Tab key
- **Smart Key Bindings**: Intuitive keyboard shortcuts for all actions
- **Color-coded Status**: Dynamic status indicators with real-time updates
- **Progressive Disclosure**: Context-sensitive information display
- **Smart Key Bindings**: Intuitive keyboard shortcuts for navigation
- **Color-coded Display**: Dynamic visual indicators for file types and status
- **Context-sensitive Information**: Detailed descriptions for each backup service
### 📦 Integrated Backup Services
### 📦 Backup Service Directories
- **🔵 Plex Backup**: Complete Plex Media Server backup with integrity checking
- **🖼️ Immich Backup**: Database and uploads backup with B2 cloud sync
- **🎬 Media Services**: Sonarr, Radarr, Prowlarr, and other media services backup
- **🔧 Environment Files**: Docker environment and configuration files backup
- **🐳 Docker Configuration**: Container and compose files backup
- **🔵 Plex Backups**: Browse Plex Media Server backup files and archives
- **🖼️ Immich Backups**: View Immich photo management backup files
- **🎬 Media Services**: Browse Sonarr, Radarr, Prowlarr, and other media service backups
- **🔧 Environment Files**: View Docker environment and configuration file backups
- **🐳 Docker Configuration**: Browse container and compose file backups
- **📊 Tautulli**: Browse Plex statistics and monitoring backups
- **📚 Audiobookshelf**: View audiobook server backup files
- **📥 SABnzbd**: Browse download client configuration backups
- **🎯 Jellyseerr**: View request management system backups
### ✅ Validation & Monitoring
### 📋 Log and Status Viewing
- **Backup Validation**: Integrity checking for all backup types
- **Real-time Monitoring**: Live backup status and progress tracking
- **Health Checks**: Comprehensive backup health monitoring
- **Status Dashboard**: Detailed status view with statistics and summaries
### 🔄 Restoration Services
- **Safe Restoration**: Validated restoration with dry-run options
- **Current Data Backup**: Automatic backup before restoration
- **Interactive Selection**: Choose from available backup files
### 🛡️ Intelligent Error Handling
- **Comprehensive Error Tracking**: Detailed error analysis and reporting
- **User-friendly Messages**: Clear error descriptions with context
- **Recovery Suggestions**: Automated recommendations for error resolution
- **Graceful Degradation**: Continues operation when individual components fail
- **Backup History**: Browse historical backup operation logs
- **File Information**: View detailed file metadata and timestamps
- **Directory Statistics**: See backup counts, sizes, and dates
- **System Configuration**: Display current system and service settings
## 🎯 Quick Start
@@ -133,79 +117,80 @@ cd tui && ./backup-manager
| `↓/j` | Move down in list |
| `←/h` | Move left (panel navigation) |
| `→/l` | Move right (panel navigation) |
| `Enter/Space` | Execute selected backup |
| `Enter` | Browse selected directory |
| `Tab` | Switch between panels |
| `v` | View backup logs |
| `s` | View backup status |
| `f` | View configuration |
| `r` | Refresh status and logs |
| `x` | Stop running backup |
| `r` | Refresh current view |
| `x` | Return to main view |
| `c` | Clear output panel |
| `Esc` | Return to main view |
| `?` | Toggle help |
| `q/Ctrl+C` | Quit application |
## 📋 Available Operations
## 📁 Available Backup Directories
### Core Backup Operations
### Backup Service Directories
1. **📦 Plex Backup** - Enhanced backup with integrity verification
2. **🖼️ Immich Backup** - Complete database and media backup
3. **🎬 Media Services Backup** - All media service configurations
4. **🔧 Environment Files Backup** - Docker environment files
5. **🐳 Docker Configuration Backup** - Container configurations
1. **📦 Plex Backups** - Browse Plex Media Server backup archives and files
2. **🖼️ Immich Backups** - View Immich photo management backup files
3. **🎬 Sonarr Backups** - Browse Sonarr TV series management backup files
4. **🎭 Radarr Backups** - View Radarr movie management backup files
5. **🔍 Prowlarr Backups** - Browse Prowlarr indexer management backup files
6. **🎯 Jellyseerr Backups** - View Jellyseerr request management backup files
7. **📥 SABnzbd Backups** - Browse SABnzbd download client backup files
8. **📊 Tautulli Backups** - View Tautulli Plex statistics backup files
9. **📚 Audiobookshelf Backups** - Browse Audiobookshelf server backup files
10. **🐳 Docker Data Backups** - View Docker container data and volume backups
11. **📋 Backup Logs** - Browse backup operation logs and history
### Validation Services
### Directory Information
1. **✅ Validate Plex Backups** - Check Plex backup integrity
2. **✅ Validate Immich Backups** - Verify Immich backups
3. **✅ Validate Environment Backups** - Check environment backup health
Each directory shows:
### Monitoring & Status
1. **📊 Monitor Plex Status** - Real-time Plex backup monitoring
### Restoration Services
1. **🔄 Restore Plex** - Safe Plex restoration with validation
2. **🔄 Restore Immich** - Immich restoration from backup
- **File listings** with names, sizes, and modification dates
- **Directory statistics** including total files and combined size
- **Backup metadata** such as compression status and service type
- **Path information** for easy navigation and reference
## 🔧 How It Works
### Script Integration
### Directory Structure Detection
The TUI integrates with your existing backup scripts:
The TUI automatically discovers and organizes backup directories:
- **Plex Scripts**: `plex/backup-plex.sh`, `plex/restore-plex.sh`, etc.
- **Immich Scripts**: `immich/backup-immich.sh`, `immich/restore-immich.sh`, etc.
- **Media Scripts**: `backup-media.sh`, `backup-env-files.sh`, etc.
- **Backup Path**: Scans `/mnt/share/media/backups/` for service directories
- **Service Recognition**: Identifies Plex, Immich, media services, and other backup folders
- **File Analysis**: Reads file metadata including sizes, dates, and compression status
- **Log Discovery**: Locates and organizes backup operation log files
### Real-time Execution
### File Browsing System
- Scripts are executed with appropriate arguments
- Output is captured and displayed in real-time
- Status is tracked and updated live
- Errors are handled gracefully with detailed reporting
- **Directory Navigation**: Browse through backup files organized by service
- **File Details**: Display comprehensive file information and metadata
- **Content Organization**: Sort files by date, size, or modification time
- **Path Tracking**: Maintain breadcrumb navigation for easy orientation
### Log Integration
### Log File Integration
- Reads from existing log files in `logs/` directories
- Parses performance data from JSON logs
- Displays recent activity and status information
- Provides searchable log viewer
- **Log File Reading**: Access backup operation logs from `logs/` directories
- **Date Parsing**: Extract timestamps and service information from log filenames
- **Content Display**: Show log contents with proper formatting and navigation
- **Historical Viewing**: Browse logs by date and service for troubleshooting
## 🎨 Interface Layout
```text
┌─── 🔧 Media & Plex Backup Manager ────┐
│┌─────────────── Services ──────────────┐┌─── Output / Logs ───┐│
││> 1. 📦 Plex Backup ││Running backup... ││
││ 2. 🖼️ Immich Backup ││ ││
││ 3. 🎬 Media Services Backup ││Status: ✅ Success ││
││ 4. ✅ Validate Plex Backups ││Duration: 45.3s ││
││ 5. 🔧 Environment Files Backup ││ ││
┌─── 📁 Backup File Browser ────────────┐
│┌─────────────── Services ──────────────┐┌─── File Details ────┐│
││> 1. 📦 Plex Backups ││📦 Plex Backups ││
││ 2. 🖼️ Immich Backups ││ ││
││ 3. 🎬 Sonarr Backups ││Files: 15 ││
││ 4. 🎭 Radarr Backups ││Size: 2.3 GB ││
││ 5. 🔍 Prowlarr Backups ││Last: 2024-01-15 ││
│└───────────────────────────────────────┘└─────────────────────┘│
│plex: ✅ 45.3s | immich: idle | Panel: Backup List │
│View: MAIN | Panel: Backup List | Path: /mnt/share/media/backups │
└──────────────────────────────────────────────────────────────────┘
```
@@ -237,33 +222,34 @@ go build -o backup-manager main.go
| Icon | Status | Description |
|------|--------|-------------|
| ✅ | Success | Operation completed successfully |
| ❌ | Error | Operation failed with errors |
| 🔄 | Running | Operation currently in progress |
| ⏸️ | Idle | Service available but not running |
| ✅ | Available | Directory exists and contains backup files |
| ❌ | Missing | Directory path not found or inaccessible |
| 📁 | Directory | Backup service directory with file contents |
| 📋 | Logs | Log files and backup operation history |
## 🚀 Advanced Usage
### Automated Operations
### File Browsing Features
The TUI integrates with your existing automation:
The TUI provides comprehensive backup file exploration:
- Cron jobs continue to work independently
- TUI provides manual execution and monitoring
- Status reflects both manual and automated runs
- **Directory Exploration**: Browse backup files organized by service type
- **File Filtering**: Navigate through files by date, size, or service
- **Metadata Display**: View detailed file information including compression status
### Script Arguments
### Backup Analysis
- Backup scripts are called with appropriate flags (`--non-interactive`, etc.)
- Restore operations use safe defaults (`--dry-run` for Plex)
- Validation scripts run with comprehensive checks
- **Size Tracking**: Monitor backup file sizes and storage usage
- **Date Analysis**: Review backup frequency and file modification dates
- **Service Organization**: Files organized by backup service for easy navigation
- **Compression Detection**: Identify compressed archives and their contents
### Log Management
### Log File Management
- View recent logs with `v` key
- Logs are sorted by timestamp (newest first)
- Real-time updates when logs change
- Integration with existing logging infrastructure
- **Log Browsing**: Navigate through backup operation logs by date and service
- **Content Viewing**: Read log file contents directly within the TUI
- **Error Investigation**: Quickly locate and review backup operation issues
- **Historical Analysis**: Track backup patterns and success rates over time
## 🔗 Integration
@@ -271,24 +257,24 @@ The TUI integrates with your existing automation:
The TUI complements your existing backup infrastructure:
- **Preserves** all existing scripts and functionality
- **Enhances** with interactive management
- **Integrates** with current logging and monitoring
- **Maintains** compatibility with automation
- **Read-Only Access**: Safely browse backup files without risk of modification
- **Log Integration**: View backup operation logs from existing automation
- **Directory Monitoring**: Track backup file creation and organization
- **Compatible Viewing**: Works alongside existing backup scripts and cron jobs
### Notification Integration
### Backup Infrastructure Viewing
- Scripts continue to send notifications (webhook, email)
- TUI provides additional visual feedback
- Status updates reflect script execution results
- Status updates reflect script execution results
- **File Discovery**: Automatically detects backup files from all services
- **Status Information**: Shows backup file health and availability
- **Log Analysis**: Provides easy access to backup operation history
- **Storage Monitoring**: Track backup storage usage and file organization
## 📝 Notes
- The TUI automatically detects the shell directory structure
- Scripts are executed from their proper directories
- Environment variables and paths are preserved
- Safe execution with proper error handling
- The TUI automatically detects backup directory structure and organization
- Provides read-only access to backup files for safe browsing and analysis
- Backup files are displayed with metadata including sizes, dates, and compression status
- Log files can be viewed directly within the interface for troubleshooting and analysis
---

BIN
tui/backup-manager
View File

Binary file not shown.

82
tui/demo-features.sh
View File

@@ -1,82 +0,0 @@
#!/bin/bash
# Enhanced Backup TUI Demonstration Script
# Shows all the advanced features implemented in the TUI
set -e
YELLOW='\033[1;33m'
GREEN='\033[0;32m'
RED='\033[0;31m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
NC='\033[0m' # No Color
clear
echo -e "${BLUE}╔══════════════════════════════════════════════════════════════════════════════╗${NC}"
echo -e "${BLUE}║ Enhanced Backup TUI Feature Demo ║${NC}"
echo -e "${BLUE}╚══════════════════════════════════════════════════════════════════════════════╝${NC}"
echo ""
echo -e "${GREEN}🎉 Successfully compiled and ready for testing!${NC}"
echo ""
echo -e "${YELLOW}Enhanced Features Implemented:${NC}"
echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo -e "${GREEN}✓ Real-time Progress Tracking${NC}"
echo " • Visual progress bars with percentage indicators"
echo " • ETA calculation based on elapsed time"
echo " • Live output streaming from backup processes"
echo ""
echo -e "${GREEN}✓ Advanced Process Management${NC}"
echo " • Context-based cancellation support"
echo " • Process monitoring and cleanup"
echo " • Graceful shutdown handling"
echo ""
echo -e "${GREEN}✓ Enhanced User Interface${NC}"
echo " • Dual-panel system (list + output)"
echo " • Multiple view modes (main, logs, status, config)"
echo " • Tab navigation between panels"
echo " • Color-coded status indicators"
echo ""
echo -e "${GREEN}✓ Intelligent Error Handling${NC}"
echo " • Comprehensive error tracking"
echo " • User-friendly error messages"
echo " • Recovery suggestions"
echo ""
echo -e "${GREEN}✓ Enhanced Key Bindings${NC}"
echo " • Enter: Execute selected backup"
echo " • x: Stop running backup"
echo " • v: View logs"
echo " • s: View status"
echo " • c: View configuration"
echo " • r: Refresh status"
echo " • Tab: Switch panels"
echo " • ?: Toggle help"
echo " • Esc: Return to main view"
echo " • q: Quit application"
echo ""
echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
echo ""
echo -e "${YELLOW}🚀 Ready to Launch!${NC}"
echo ""
echo -e "${GREEN}To start the enhanced backup TUI, run:${NC}"
echo -e "${BLUE} cd ~/shell/tui && ./backup-manager${NC}"
echo ""
echo -e "${YELLOW}💡 Pro Tips:${NC}"
echo "• Use the dry-run options first to test backups safely"
echo "• Monitor the progress bars and ETA calculations"
echo "• Try canceling a backup with 'x' to test process management"
echo "• Switch between panels with Tab to see different views"
echo "• Use 'r' to refresh status and see real-time updates"
echo ""
echo -e "${GREEN}The enhanced backup TUI is now ready for production use! 🎯${NC}"