EZ-Homelab/EZ-Homelab TUI-PRD.md

EZ-Homelab TUI Deployment Script - Product Requirements Document

Executive Summary

The EZ-Homelab TUI Deployment Script is a modern, user-friendly replacement for the existing complex bash deployment script. It provides an interactive terminal user interface (TUI) for deploying and managing a comprehensive homelab infrastructure using Docker Compose stacks, with support for automated deployment via configuration files.

Objectives

Primary Objectives

• Replace the complex 1000+ line bash script with a maintainable Python TUI application
• Provide three distinct deployment scenarios: Single Server Full, Core Server, and Remote Server
• Enable both interactive and fully automated deployment workflows
• Handle complete system setup including Docker and NVIDIA GPU configuration
• Ensure maximum user convenience by minimizing required logouts/reboots

Secondary Objectives

• Improve user experience with modern TUI design using Rich + Questionary
• Provide flexible service selection and configuration options
• Support save-only mode for configuration preparation
• Include comprehensive validation and error handling
• Maintain backward compatibility with existing .env configurations

Target Users

Primary Users

• Homelab Enthusiasts: Users setting up personal server infrastructure
• Self-Hosters: Individuals deploying media servers, productivity tools, and monitoring
• System Administrators: Those managing small-scale server deployments

User Personas

1. Alex the Homelab Beginner: New to self-hosting, needs guided setup with sensible defaults
2. Jordan the Power User: Experienced user who wants fine-grained control over service selection
3. Sam the DevOps Engineer: Needs automated deployment for multiple servers, prefers configuration files

Technical Requirements

• Ubuntu/Debian Linux systems (primary target)
• Basic command-line familiarity
• Internet access for package downloads
• Administrative privileges (sudo access)

Functional Requirements

Core Features

1. Deployment Scenarios

FR-DEP-001: Support three deployment scenarios

• Single Server Full: Deploy all core, infrastructure, and dashboard services
• Core Server: Deploy only core infrastructure and dashboards
• Remote Server: Deploy infrastructure and dashboards without core services

FR-DEP-002: Automated scenario selection based on user choice

• Pre-select appropriate services for each scenario
• Allow user customization within scenario constraints

2. Configuration Management

FR-CONF-001: Load existing .env configuration

• Parse existing .env file on startup
• Validate configuration completeness
• Pre-populate TUI defaults with existing values

FR-CONF-002: Support deployment configuration section in .env

• Parse [DEPLOYMENT] section with service selections
• Enable fully automated deployment with --yes flag
• Validate deployment configuration completeness

FR-CONF-003: Interactive configuration collection

• Skip questions for valid existing values
• Provide sensible defaults for all settings
• Validate user input in real-time

3. System Setup & Prerequisites

FR-SYS-001: Pre-flight system checks

• OS compatibility (Ubuntu/Debian)
• Available disk space (>10GB)
• Internet connectivity
• System architecture validation

FR-SYS-002: Docker installation and configuration

• Detect existing Docker installation
• Install Docker if missing
• Add user to docker group
• Avoid requiring logout through smart command execution

FR-SYS-003: NVIDIA GPU support

• Detect NVIDIA GPU presence
• Install official NVIDIA drivers using official installers
• Install NVIDIA Container Toolkit
• Handle reboot requirements intelligently

FR-SYS-004: Dependency management

• Install required system packages
• Install Python dependencies (Rich, Questionary, python-dotenv)
• Update system packages as needed

4. Service Selection & Customization

FR-SVC-001: Core services selection

• Display scenario-appropriate core services
• Allow include/exclude for flexibility
• Enforce minimum requirements for each scenario

FR-SVC-002: Infrastructure services selection

• Provide checkbox interface for all infrastructure services
• Include descriptions and default selections
• Allow complete customization

FR-SVC-003: Additional stacks preparation

• Multi-select interface for optional service stacks
• Copy selected stacks to /opt/stacks/ without starting
• Enable later deployment via Dockge

5. User Interface & Experience

FR-UI-001: Interactive TUI design

• Use Rich + Questionary for modern terminal interface
• Provide clear, descriptive prompts
• Include help text and validation messages

FR-UI-002: Conditional question flow

• Show questions only when relevant
• Skip questions with valid existing values
• Provide logical question progression

FR-UI-003: Configuration summary and confirmation

• Display formatted summary of all settings
• Allow review before proceeding
• Provide options to save, change, or exit

6. Deployment Execution

FR-DEP-003: One-step deployment process

• Handle all installation and deployment in single script run
• Minimize required logouts/reboots
• Provide clear progress indication

FR-DEP-004: Smart reboot handling

• Detect what requires reboot vs logout vs nothing
• Perform reboot-requiring actions last
• Support both automatic and manual reboot options

FR-DEP-005: Error handling and recovery

• Provide clear error messages
• Allow recovery from partial failures
• Maintain configuration state across retries

Command Line Interface

Launch Options

FR-CLI-001: Support multiple launch modes

• Interactive mode (default): Full TUI experience
• Automated mode (--yes): Use complete .env configuration
• Save-only mode (--save-only): Collect configuration without deploying
• Help mode (--help): Display usage information

Configuration Output

FR-CLI-002: Flexible configuration saving

• Save to .env by default
• Allow custom filename specification
• Preserve existing .env structure and comments

Non-Functional Requirements

Performance

NFR-PERF-001: Fast startup and validation

• Complete pre-flight checks within 30 seconds
• Validate .env file parsing within 5 seconds
• Provide responsive TUI interaction

NFR-PERF-002: Efficient deployment

• Complete full deployment within 15-30 minutes
• Provide real-time progress indication
• Handle large downloads gracefully

Reliability

NFR-REL-001: Robust error handling

• Graceful handling of network failures
• Clear error messages with recovery suggestions
• Maintain system stability during installation

NFR-REL-002: Configuration validation

• Validate all user inputs before proceeding
• Check for conflicting configurations
• Prevent deployment with invalid settings

Usability

NFR-USAB-001: Intuitive interface design

• Clear, descriptive prompts and help text
• Logical question flow and grouping
• Consistent terminology and formatting

NFR-USAB-002: Accessibility considerations

• Support keyboard navigation
• Provide clear visual feedback
• Include progress indicators for long operations

Security

NFR-SEC-001: Secure credential handling

• Mask password inputs in TUI
• Store credentials securely in .env
• Validate certificate and token formats

NFR-SEC-002: Safe system modifications

• Require explicit user confirmation for system changes
• Provide clear warnings for potentially disruptive actions
• Maintain secure file permissions

Compatibility

NFR-COMP-001: OS compatibility

• Primary support for Ubuntu 20.04+ and Debian 11+
• Graceful handling of different package managers
• Architecture support for amd64 and arm64

NFR-COMP-002: Backward compatibility

• Read existing .env files without modification
• Support legacy configuration formats
• Provide migration path for old configurations

Technical Requirements

Technology Stack

TR-TECH-001: Core technologies

• Python 3.8+ as runtime environment
• Rich library for terminal formatting
• Questionary library for interactive prompts
• python-dotenv for configuration parsing

TR-TECH-002: System integration

• Docker and Docker Compose for container management
• systemd for service management
• apt/dpkg for package management
• Official NVIDIA installation tools

Architecture

TR-ARCH-001: Modular design

• Separate concerns for UI, validation, and deployment
• Configurable question flow engine
• Pluggable deployment modules

TR-ARCH-002: State management

• Maintain configuration state throughout TUI flow
• Support save/restore of partial configurations
• Handle interruption and resumption gracefully

Dependencies

TR-DEPS-001: Python packages

• rich>=12.0.0
• questionary>=1.10.0
• python-dotenv>=0.19.0
• pyyaml>=6.0 (for configuration parsing)

TR-DEPS-002: System packages

• curl, wget, git (for downloads and version control)
• htop, nano, vim (system monitoring and editing)
• ufw, fail2ban (security)
• unattended-upgrades, apt-listchanges (system maintenance)
• sshpass (for multi-server setup)

User Experience Requirements

Onboarding Flow

UX-ONB-001: First-time user experience

• Clear welcome message and overview
• Guided setup with sensible defaults
• Help text for each question

UX-ONB-002: Returning user experience

• Load existing configuration automatically
• Skip redundant questions
• Provide quick confirmation for known setups

Interaction Patterns

UX-INT-001: Question flow optimization

• Group related questions together
• Provide progress indication
• Allow backtracking and editing

UX-INT-002: Feedback and validation

• Real-time input validation
• Clear error messages with suggestions
• Success confirmations for completed steps

Error Recovery

UX-ERR-001: Graceful error handling

• Clear error descriptions
• Suggested recovery actions
• Option to retry or modify configuration

UX-ERR-002: Partial failure recovery

• Save progress on interruption
• Allow resumption from last completed step
• Provide rollback options where possible

Success Criteria

Functional Completeness

• All three deployment scenarios work correctly
• Automated deployment with --yes flag functions
• Save-only mode preserves configuration
• Docker and NVIDIA installation work reliably
• Service selection and customization work as specified

User Experience

• TUI is intuitive and responsive
• Configuration validation prevents errors
• Error messages are helpful and actionable
• Deployment completes without requiring logout/reboot (except when absolutely necessary)

Technical Quality

• Code is well-structured and maintainable
• Comprehensive error handling implemented
• Configuration parsing is robust
• System integration works reliably across Ubuntu/Debian versions

Performance Targets

• Pre-flight checks complete within 30 seconds
• TUI startup within 5 seconds
• Full deployment completes within 30 minutes
• Memory usage remains under 200MB during execution

Implementation Plan

Phase 1: Core Infrastructure (Week 1-2)

• Set up Python project structure
• Implement basic TUI framework with Rich + Questionary
• Create configuration parsing and validation
• Implement pre-flight system checks

Phase 2: System Setup (Week 3-4)

• Implement Docker installation and configuration
• Add NVIDIA GPU detection and official driver installation
• Create dependency management system
• Implement smart reboot/logout handling

Phase 3: Configuration Management (Week 5-6)

• Build dynamic question flow engine
• Implement .env parsing and [DEPLOYMENT] section support
• Create configuration validation system
• Add save-only functionality

Phase 4: Deployment Logic (Week 7-8)

• Implement deployment scenario logic
• Create service selection and preparation system
• Build deployment execution engine
• Add progress indication and error handling

Phase 5: Testing & Polish (Week 9-10)

• Comprehensive testing across Ubuntu/Debian versions
• User experience testing and refinement
• Documentation and help system
• Performance optimization

Dependencies & Constraints

External Dependencies

• NVIDIA Official Installers: Must use official NVIDIA installation methods
• Docker Official Installation: Use official Docker installation scripts
• Ubuntu/Debian Package Repositories: Rely on standard package sources

Technical Constraints

• Python Version: Minimum Python 3.8 required for modern type hints
• Terminal Compatibility: Must work in standard Linux terminals
• Network Requirements: Internet access required for downloads
• Privilege Requirements: sudo access required for system modifications

Business Constraints

• Open Source: Must remain free and open source
• Backward Compatibility: Should not break existing .env files
• Documentation: Comprehensive documentation required
• Community Support: Should be maintainable by community contributors

Risk Assessment

High Risk Items

• NVIDIA Installation: Complex driver installation across different GPU models
• Reboot Handling: Ensuring one-step installation without logout requirements
• Configuration Validation: Complex validation logic for interdependent settings

Mitigation Strategies

• Testing: Extensive testing on multiple hardware configurations
• Fallback Options: Provide manual installation instructions as backup
• Modular Design: Allow components to be disabled/enabled independently
• User Communication: Clear warnings and alternative options for complex scenarios

Future Enhancements

Planned Features

• Support for additional Linux distributions
• Web-based configuration interface
• Integration with configuration management tools
• Advanced deployment templates and presets

Maintenance Considerations

• Regular updates for new NVIDIA driver versions
• Compatibility testing with new Ubuntu/Debian releases
• Community contribution guidelines and testing frameworks

---

This PRD serves as the authoritative specification for the EZ-Homelab TUI Deployment Script. All development decisions should reference this document to ensure alignment with user requirements and technical constraints. c:\Users\kelin\Documents\Apps\GitHub\EZ-Homelab\EZ-Homelab TUI-PRD.md