bzzz/deployments/bare-metal/WEB_UI_DEVELOPMENT_PLAN.md

BZZZ Web Installation/Configuration Development Plan

Overview

This plan leverages existing BZZZ infrastructure to implement the missing web-based installation and configuration functionality without reinventing the wheel. We'll integrate the existing config-ui with our enhanced installer and BZZZ's existing systems.

Existing Infrastructure Analysis

✅ What We Already Have

1. HTTP API Server (api/http_server.go)

   • Existing HTTP server with CORS support
   • Health endpoints (/api/health, /api/status)
   • Hypercore log API endpoints
   • Gorilla Mux router setup

2. Config UI Foundation (install/config-ui/)

   • Complete Next.js 14 setup
   • 8-step setup wizard framework
   • TypeScript + Tailwind CSS
   • Component structure already defined
   • Progress tracking and navigation

3. Task Coordinator (coordinator/task_coordinator.go)

   • Agent management and role assignment
   • Repository integration framework
   • Status reporting capabilities

4. Configuration System (pkg/config/)

   • YAML configuration management
   • Role and agent configuration
   • Network and service settings

5. Repository Integration (repository/factory.go)

   • GITEA and GitHub providers
   • Task management interfaces
   • Credential handling

Implementation Strategy

Phase 1: Backend API Integration (1-2 days)

1.1 Extend HTTP Server with Setup APIs

File: api/http_server.go

Add new endpoints to existing server:

// Setup and configuration endpoints
api.HandleFunc("/setup/system", h.handleSystemInfo).Methods("GET")
api.HandleFunc("/setup/network", h.handleNetworkConfig).Methods("GET", "POST")
api.HandleFunc("/setup/security", h.handleSecurityConfig).Methods("GET", "POST")
api.HandleFunc("/setup/ai", h.handleAIConfig).Methods("GET", "POST")
api.HandleFunc("/setup/resources", h.handleResourceConfig).Methods("GET", "POST")
api.HandleFunc("/setup/deploy", h.handleServiceDeploy).Methods("POST")
api.HandleFunc("/setup/cluster", h.handleClusterConfig).Methods("GET", "POST")
api.HandleFunc("/setup/validate", h.handleValidation).Methods("POST")

// Repository configuration (integrate with existing factory)
api.HandleFunc("/setup/repository", h.handleRepositoryConfig).Methods("GET", "POST")

1.2 System Detection Integration

Leverage existing system info from enhanced installer:

func (h *HTTPServer) handleSystemInfo(w http.ResponseWriter, r *http.Request) {
    info := map[string]interface{}{
        "os":           detectOS(),           // From enhanced installer
        "architecture": detectArchitecture(), // From enhanced installer  
        "hardware":     detectHardware(),     // New GPU detection
        "network":      detectNetwork(),      // Network interface discovery
        "services":     detectServices(),     // Docker, Ollama status
    }
    json.NewEncoder(w).Encode(info)
}

1.3 Configuration Management

Extend existing config system to support web updates:

// New file: api/setup_handlers.go
type SetupManager struct {
    configPath   string
    coordinator  *coordinator.TaskCoordinator
    repoFactory  *repository.DefaultProviderFactory
}

func (s *SetupManager) UpdateNetworkConfig(config NetworkConfig) error {
    // Update YAML configuration
    // Restart network services if needed
    // Validate connectivity
}

Phase 2: Web UI Enhancement (2-3 days)

2.1 Complete Existing Components

The config-ui framework exists but components need implementation:

SystemDetection.tsx - Leverage system detection API:

const SystemDetection = ({ onComplete, systemInfo }) => {
    // Display detected hardware (GPU detection for Parallama)
    // Show system requirements validation
    // Network interface selection
    // Prerequisite checking
}

NetworkConfiguration.tsx - Network setup:

const NetworkConfiguration = ({ onComplete, configData }) => {
    // Port configuration (8080, 8081, 4001)
    // Firewall rules setup
    // Network interface selection
    // Connectivity testing
}

SecuritySetup.tsx - Security configuration:

const SecuritySetup = ({ onComplete, configData }) => {
    // SSH key generation/upload (for cluster deployment)
    // TLS certificate setup
    // Authentication method selection
    // Security policy configuration
}

2.2 Repository Integration Component

File: install/config-ui/app/setup/components/RepositoryConfiguration.tsx

const RepositoryConfiguration = ({ onComplete, configData }) => {
    // GITEA/GitHub provider selection
    // Credential input and validation
    // Repository access testing
    // Task label configuration
    // Integration with existing repository factory
}

2.3 AI Configuration Enhancement

AIConfiguration.tsx - GPU optimization:

const AIConfiguration = ({ onComplete, systemInfo }) => {
    // GPU detection display
    // Parallama vs Ollama recommendation
    // OpenAI API configuration
    // Model selection and downloading
    // Resource allocation per model
}

Phase 3: Installer Integration (1 day)

3.1 Enhanced Installer Web Mode

File: /home/tony/chorus/project-queues/active/chorus.services/installer/install-chorus-enhanced.sh

Add web UI mode option:

# Add new command line option
while [[ $# -gt 0 ]]; do
    case $1 in
        --web-ui)
            ENABLE_WEB_UI=true
            shift
            ;;
        # ... existing options
    esac
done

# After basic installation
if [[ "$ENABLE_WEB_UI" == "true" ]]; then
    setup_web_ui
fi

setup_web_ui() {
    log_step "Setting up web configuration interface..."
    
    # Copy config-ui to BZZZ directory
    cp -r "$BZZZ_DIR/../install/config-ui" "$BZZZ_DIR/web-ui"
    
    # Install Node.js and dependencies
    install_nodejs
    cd "$BZZZ_DIR/web-ui" && npm install
    
    # Start web UI in background
    npm run build && npm run start &
    
    echo ""
    echo "🌐 Web configuration available at: http://$(hostname):8080/setup"
    echo "⚡ Continue setup in your browser"
}

3.2 Hybrid Installation Flow

# Enhanced installer usage options:
curl -fsSL https://chorus.services/install-enhanced.sh | sh                    # CLI mode (current)
curl -fsSL https://chorus.services/install-enhanced.sh | sh -s -- --web-ui    # Web mode (new)

Phase 4: Cluster Deployment Integration (2-3 days)

4.1 SSH Deployment System

File: api/cluster_deployment.go

type ClusterDeployer struct {
    sshConfig   SSHConfig
    installer   string  // Enhanced installer script
    coordinator *coordinator.TaskCoordinator
}

func (c *ClusterDeployer) DeployToNodes(nodes []NodeConfig) error {
    for _, node := range nodes {
        // SSH to remote node
        // Execute enhanced installer with node-specific config
        // Verify installation
        // Add to cluster coordination
    }
}

4.2 Cluster Formation Component

ClusterFormation.tsx - Multi-node coordination:

const ClusterFormation = ({ onComplete, configData }) => {
    // Node discovery (SSH-based or manual IP entry)
    // SSH credential configuration
    // Remote deployment progress tracking
    // Cluster validation and health checking
    // P2P network formation verification
}

4.3 P2P Network Integration

Leverage existing P2P infrastructure:

// Integration with existing p2p/node.go
func (h *HTTPServer) handleClusterConfig(w http.ResponseWriter, r *http.Request) {
    // Use existing P2P node configuration
    // Coordinate with task coordinator
    // Enable automatic peer discovery
}

Phase 5: Professional Installation Experience (1-2 days)

5.1 Enhanced Installation Output

# Professional branded installer output
print_professional_banner() {
    echo -e "${PURPLE}"
    cat << 'EOF'
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    🔥 BZZZ Distributed AI Coordination Platform
       Professional Installation System v2.0
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EOF
    echo -e "${NC}"
}

show_installation_progress() {
    local step="$1"
    local total="$2"
    local message="$3"
    
    echo -e "${BLUE}[$step/$total]${NC} $message"
    
    # Progress bar
    local progress=$((step * 100 / total))
    printf "Progress: ["
    for ((i=0; i<progress/5; i++)); do printf "█"; done
    for ((i=progress/5; i<20; i++)); do printf "░"; done
    printf "] %d%%\n" $progress
}

5.2 GPU Detection and Parallama Integration

detect_gpu_configuration() {
    log_step "Analyzing GPU configuration..."
    
    # Detect NVIDIA GPUs
    if command -v nvidia-smi >/dev/null 2>&1; then
        GPU_COUNT=$(nvidia-smi --list-gpus | wc -l)
        GPU_INFO=$(nvidia-smi --query-gpu=name,memory.total --format=csv,noheader)
        
        if [[ $GPU_COUNT -gt 1 ]]; then
            echo ""
            echo -e "${GREEN}🚀 Multi-GPU Setup Detected ($GPU_COUNT NVIDIA GPUs)${NC}"
            echo -e "${CYAN}Parallama is RECOMMENDED for optimal multi-GPU performance!${NC}"
            echo ""
            echo "Detected GPUs:"
            echo "$GPU_INFO" | sed 's/^/  • /'
            echo ""
            
            read -p "Install Parallama (recommended) or standard Ollama? [P/o]: " choice
            case $choice in
                [Oo]* ) INSTALL_OLLAMA_TYPE="standard" ;;
                * ) INSTALL_OLLAMA_TYPE="parallama" ;;
            esac
        fi
    fi
}

Implementation Timeline

Week 1: Backend Foundation

• Day 1-2: Extend HTTP server with setup APIs
• Day 3-4: Implement system detection and configuration management
• Day 5: Repository integration and credential handling

Week 2: Web UI Development

• Day 1-2: Complete existing setup components
• Day 3-4: Repository configuration and AI setup components
• Day 5: Integration testing and UI polish

Week 3: Cluster and Professional Features

• Day 1-2: SSH deployment system and cluster formation
• Day 3-4: Professional installation experience and GPU detection
• Day 5: End-to-end testing and documentation

Leveraging Existing BZZZ Systems

✅ Reuse Without Modification

1. HTTP Server Architecture - Extend existing api/http_server.go
2. Configuration System - Use existing pkg/config/ YAML management
3. Repository Integration - Leverage repository/factory.go providers
4. Task Coordination - Integrate with coordinator/task_coordinator.go
5. P2P Networking - Use existing p2p/node.go infrastructure

🔧 Extend Existing Systems

1. Enhanced Installer - Add web UI mode to existing script
2. Config UI Framework - Complete existing component implementations
3. API Endpoints - Add setup endpoints to existing HTTP server
4. System Detection - Enhance existing OS detection with hardware profiling

🆕 New Components Needed

1. Cluster Deployment Manager - SSH-based remote installation
2. GPU Detection System - Hardware profiling and Parallama integration
3. Professional Installation UX - Enhanced progress and branding
4. Setup API Handlers - Backend logic for web configuration

Integration Points

Repository Integration

// Leverage existing repository factory
func (h *HTTPServer) handleRepositoryConfig(w http.ResponseWriter, r *http.Request) {
    factory := &repository.DefaultProviderFactory{}
    
    // Create provider based on web UI input
    provider, err := factory.CreateProvider(ctx, repoConfig)
    
    // Test connectivity
    // Store configuration
    // Update task coordinator
}

Task Coordinator Integration

// Use existing task coordinator for cluster management
func (h *HTTPServer) handleClusterStatus(w http.ResponseWriter, r *http.Request) {
    status := h.taskCoordinator.GetStatus()
    json.NewEncoder(w).Encode(status)
}

Configuration Management

// Extend existing config system
func (s *SetupManager) SaveConfiguration(config SetupConfig) error {
    // Convert web config to BZZZ YAML format
    // Use existing config.Config struct
    // Restart services as needed
}

Success Metrics

Technical Completeness

• Web UI accessible at :8080/setup
• 8-step configuration wizard functional
• GPU detection and Parallama recommendation
• SSH-based cluster deployment
• Repository integration (GITEA/GitHub)
• Professional installation experience

User Experience

• Single-command installation with web option
• Intuitive progress tracking and navigation
• Real-time validation and error handling
• Mobile-responsive design
• Comprehensive help and documentation

Integration Quality

• Seamless integration with existing BZZZ systems
• No disruption to current enhanced installer
• Proper error handling and rollback
• Production-ready security and performance

Risk Mitigation

Technical Risks

• API Integration Complexity: Use existing HTTP server patterns
• Configuration Conflicts: Maintain YAML compatibility
• Service Coordination: Leverage existing task coordinator

User Experience Risks

• Installation Complexity: Provide both CLI and web options
• Error Recovery: Implement proper rollback mechanisms
• Performance: Optimize for low-resource environments

Conclusion

This plan leverages 80% of existing BZZZ infrastructure while delivering the professional web-based installation experience envisioned in the original plans. By extending rather than replacing existing systems, we minimize development time and maintain compatibility with current deployments.

Key Benefits:

• ✅ Rapid implementation using existing code
• ✅ Maintains backward compatibility
• ✅ Professional installation experience
• ✅ Complete feature parity with original vision
• ✅ Seamless integration with enhanced installer