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 | | 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 | | `←/h` | Move left (panel navigation) | Switch to service list panel |
| `→/l` | Move right (panel navigation) | Switch to output panel | | `→/l` | Move right (panel navigation) | Switch to output panel |
| `Tab` | Switch between panels | Toggle between service list and output | | `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 ### View Management
| Key | Action | Description | | Key | Action | Description |
|-----|--------|-------------| |-----|--------|-------------|
| `v` | View backup logs | Switch to logs view with real-time updates | | `v` | View backup logs | Switch to logs view |
| `s` | View backup status | Display comprehensive status dashboard | | `s` | View backup status | Display backup file status information |
| `c` | View configuration | Show system and service configuration | | `f` | View configuration | Show system and service configuration |
| `r` | Refresh status and logs | Reload all status information | | `r` | Refresh current view | Reload directory and status information |
| `Esc` | Return to main view | Go back to main backup selection | | `Esc` | Return to main view | Go back to main backup selection |
### Process Control ### Interface Control
| Key | Action | Description | | Key | Action | Description |
|-----|--------|-------------| |-----|--------|-------------|
| `x` | Stop running backup | Gracefully cancel active backup process | | `c` | Clear output panel | Clear the output display area |
| `Space` | Clear output panel | Clear the output display area |
| `?` | Toggle help | Show/hide comprehensive help information | | `?` | Toggle help | Show/hide comprehensive help information |
| `q/Ctrl+C` | Quit application | Exit the TUI application | | `q/Ctrl+C` | Quit application | Exit the TUI application |
### Advanced Features ## 🚀 Features
| Key | Action | Description | ### 📁 File Browser Interface
|-----|--------|-------------|
| `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.
## 🚀 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 - **Backup Statistics**: View file counts, total sizes, and backup ages
- **ETA Calculations**: Intelligent time estimation based on current progress - **Status Information**: Display backup directory health and availability
- **Output Streaming**: Real-time display of backup command output - **Configuration Details**: Show system and service configuration information
- **Performance Metrics**: Elapsed time tracking and transfer statistics - **File Metadata**: Display compressed file status and service associations
### 🎛️ Advanced Process Management ### 🖥️ User Interface
- **Context Cancellation**: Graceful backup cancellation with context support - **Dual-panel System**: Service list and detailed information viewer
- **Process Monitoring**: Track and control multiple simultaneous backups - **Multiple View Modes**: Main browser, logs viewer, status, and configuration views
- **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
- **Tab Navigation**: Switch between panels with Tab key - **Tab Navigation**: Switch between panels with Tab key
- **Smart Key Bindings**: Intuitive keyboard shortcuts for all actions - **Smart Key Bindings**: Intuitive keyboard shortcuts for navigation
- **Color-coded Status**: Dynamic status indicators with real-time updates - **Color-coded Display**: Dynamic visual indicators for file types and status
- **Progressive Disclosure**: Context-sensitive information display - **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 - **🔵 Plex Backups**: Browse Plex Media Server backup files and archives
- **🖼️ Immich Backup**: Database and uploads backup with B2 cloud sync - **🖼️ Immich Backups**: View Immich photo management backup files
- **🎬 Media Services**: Sonarr, Radarr, Prowlarr, and other media services backup - **🎬 Media Services**: Browse Sonarr, Radarr, Prowlarr, and other media service backups
- **🔧 Environment Files**: Docker environment and configuration files backup - **🔧 Environment Files**: View Docker environment and configuration file backups
- **🐳 Docker Configuration**: Container and compose files backup - **🐳 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 - **Backup History**: Browse historical backup operation logs
- **Real-time Monitoring**: Live backup status and progress tracking - **File Information**: View detailed file metadata and timestamps
- **Health Checks**: Comprehensive backup health monitoring - **Directory Statistics**: See backup counts, sizes, and dates
- **Status Dashboard**: Detailed status view with statistics and summaries - **System Configuration**: Display current system and service settings
### 🔄 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
## 🎯 Quick Start ## 🎯 Quick Start
@@ -133,79 +117,80 @@ cd tui && ./backup-manager
| `↓/j` | Move down in list | | `↓/j` | Move down in list |
| `←/h` | Move left (panel navigation) | | `←/h` | Move left (panel navigation) |
| `→/l` | Move right (panel navigation) | | `→/l` | Move right (panel navigation) |
| `Enter/Space` | Execute selected backup | | `Enter` | Browse selected directory |
| `Tab` | Switch between panels | | `Tab` | Switch between panels |
| `v` | View backup logs | | `v` | View backup logs |
| `s` | View backup status | | `s` | View backup status |
| `f` | View configuration | | `f` | View configuration |
| `r` | Refresh status and logs | | `r` | Refresh current view |
| `x` | Stop running backup | | `x` | Return to main view |
| `c` | Clear output panel | | `c` | Clear output panel |
| `Esc` | Return to main view | | `Esc` | Return to main view |
| `?` | Toggle help | | `?` | Toggle help |
| `q/Ctrl+C` | Quit application | | `q/Ctrl+C` | Quit application |
## 📋 Available Operations ## 📁 Available Backup Directories
### Core Backup Operations ### Backup Service Directories
1. **📦 Plex Backup** - Enhanced backup with integrity verification 1. **📦 Plex Backups** - Browse Plex Media Server backup archives and files
2. **🖼️ Immich Backup** - Complete database and media backup 2. **🖼️ Immich Backups** - View Immich photo management backup files
3. **🎬 Media Services Backup** - All media service configurations 3. **🎬 Sonarr Backups** - Browse Sonarr TV series management backup files
4. **🔧 Environment Files Backup** - Docker environment files 4. **🎭 Radarr Backups** - View Radarr movie management backup files
5. **🐳 Docker Configuration Backup** - Container configurations 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 Each directory shows:
2. **✅ Validate Immich Backups** - Verify Immich backups
3. **✅ Validate Environment Backups** - Check environment backup health
### Monitoring & Status - **File listings** with names, sizes, and modification dates
- **Directory statistics** including total files and combined size
1. **📊 Monitor Plex Status** - Real-time Plex backup monitoring - **Backup metadata** such as compression status and service type
- **Path information** for easy navigation and reference
### Restoration Services
1. **🔄 Restore Plex** - Safe Plex restoration with validation
2. **🔄 Restore Immich** - Immich restoration from backup
## 🔧 How It Works ## 🔧 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. - **Backup Path**: Scans `/mnt/share/media/backups/` for service directories
- **Immich Scripts**: `immich/backup-immich.sh`, `immich/restore-immich.sh`, etc. - **Service Recognition**: Identifies Plex, Immich, media services, and other backup folders
- **Media Scripts**: `backup-media.sh`, `backup-env-files.sh`, etc. - **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 - **Directory Navigation**: Browse through backup files organized by service
- Output is captured and displayed in real-time - **File Details**: Display comprehensive file information and metadata
- Status is tracked and updated live - **Content Organization**: Sort files by date, size, or modification time
- Errors are handled gracefully with detailed reporting - **Path Tracking**: Maintain breadcrumb navigation for easy orientation
### Log Integration ### Log File Integration
- Reads from existing log files in `logs/` directories - **Log File Reading**: Access backup operation logs from `logs/` directories
- Parses performance data from JSON logs - **Date Parsing**: Extract timestamps and service information from log filenames
- Displays recent activity and status information - **Content Display**: Show log contents with proper formatting and navigation
- Provides searchable log viewer - **Historical Viewing**: Browse logs by date and service for troubleshooting
## 🎨 Interface Layout ## 🎨 Interface Layout
```text ```text
┌─── 🔧 Media & Plex Backup Manager ────┐ ┌─── 📁 Backup File Browser ────────────┐
│┌─────────────── Services ──────────────┐┌─── Output / Logs ───┐│ │┌─────────────── Services ──────────────┐┌─── File Details ────┐│
││> 1. 📦 Plex Backup ││Running backup... ││ ││> 1. 📦 Plex Backups ││📦 Plex Backups ││
││ 2. 🖼️ Immich Backup ││ ││ ││ 2. 🖼️ Immich Backups ││ ││
││ 3. 🎬 Media Services Backup ││Status: ✅ Success ││ ││ 3. 🎬 Sonarr Backups ││Files: 15 ││
││ 4. ✅ Validate Plex Backups ││Duration: 45.3s ││ ││ 4. 🎭 Radarr Backups ││Size: 2.3 GB ││
││ 5. 🔧 Environment Files Backup ││ ││ ││ 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 | | Icon | Status | Description |
|------|--------|-------------| |------|--------|-------------|
| ✅ | Success | Operation completed successfully | | ✅ | Available | Directory exists and contains backup files |
| ❌ | Error | Operation failed with errors | | ❌ | Missing | Directory path not found or inaccessible |
| 🔄 | Running | Operation currently in progress | | 📁 | Directory | Backup service directory with file contents |
| ⏸️ | Idle | Service available but not running | | 📋 | Logs | Log files and backup operation history |
## 🚀 Advanced Usage ## 🚀 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 - **Directory Exploration**: Browse backup files organized by service type
- TUI provides manual execution and monitoring - **File Filtering**: Navigate through files by date, size, or service
- Status reflects both manual and automated runs - **Metadata Display**: View detailed file information including compression status
### Script Arguments ### Backup Analysis
- Backup scripts are called with appropriate flags (`--non-interactive`, etc.) - **Size Tracking**: Monitor backup file sizes and storage usage
- Restore operations use safe defaults (`--dry-run` for Plex) - **Date Analysis**: Review backup frequency and file modification dates
- Validation scripts run with comprehensive checks - **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 - **Log Browsing**: Navigate through backup operation logs by date and service
- Logs are sorted by timestamp (newest first) - **Content Viewing**: Read log file contents directly within the TUI
- Real-time updates when logs change - **Error Investigation**: Quickly locate and review backup operation issues
- Integration with existing logging infrastructure - **Historical Analysis**: Track backup patterns and success rates over time
## 🔗 Integration ## 🔗 Integration
@@ -271,24 +257,24 @@ The TUI integrates with your existing automation:
The TUI complements your existing backup infrastructure: The TUI complements your existing backup infrastructure:
- **Preserves** all existing scripts and functionality - **Read-Only Access**: Safely browse backup files without risk of modification
- **Enhances** with interactive management - **Log Integration**: View backup operation logs from existing automation
- **Integrates** with current logging and monitoring - **Directory Monitoring**: Track backup file creation and organization
- **Maintains** compatibility with automation - **Compatible Viewing**: Works alongside existing backup scripts and cron jobs
### Notification Integration ### Backup Infrastructure Viewing
- Scripts continue to send notifications (webhook, email) - **File Discovery**: Automatically detects backup files from all services
- TUI provides additional visual feedback - **Status Information**: Shows backup file health and availability
- Status updates reflect script execution results - **Log Analysis**: Provides easy access to backup operation history
- Status updates reflect script execution results - **Storage Monitoring**: Track backup storage usage and file organization
## 📝 Notes ## 📝 Notes
- The TUI automatically detects the shell directory structure - The TUI automatically detects backup directory structure and organization
- Scripts are executed from their proper directories - Provides read-only access to backup files for safe browsing and analysis
- Environment variables and paths are preserved - Backup files are displayed with metadata including sizes, dates, and compression status
- Safe execution with proper error handling - 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}"