bzzz/deployments/bare-metal/INSTALLATION_SYSTEM.md

# BZZZ Installation System

A comprehensive one-command installation system for BZZZ distributed AI coordination platform, similar to Ollama's approach.

## Overview

The BZZZ installation system provides:
- **One-command installation**: `curl -fsSL https://chorus.services/install.sh | sh`
- **Automated system detection**: Hardware, OS, and network configuration
- **GPU-aware setup**: Detects NVIDIA/AMD GPUs and recommends Parallama for multi-GPU systems
- **Web-based configuration**: Beautiful React-based setup wizard
- **Production-ready deployment**: Systemd services, monitoring, and security

## Installation Architecture

### Phase 1: System Detection & Installation
1. **System Requirements Check**
   - OS compatibility (Ubuntu, Debian, CentOS, RHEL, Fedora)
   - Architecture support (amd64, arm64, armv7)
   - Minimum resources (2GB RAM, 10GB disk)

2. **Hardware Detection**
   - CPU cores and model
   - Available memory
   - Storage capacity
   - GPU configuration (NVIDIA/AMD)
   - Network interfaces

3. **Dependency Installation**
   - Docker and Docker Compose
   - System utilities (curl, wget, jq, etc.)
   - GPU drivers (if applicable)

4. **AI Model Platform Choice**
   - **Parallama (Recommended for Multi-GPU)**: Our multi-GPU fork of Ollama
   - **Standard Ollama**: Traditional single-GPU Ollama
   - **Skip**: Configure later via web UI

### Phase 2: BZZZ Installation
1. **Binary Installation**
   - Download architecture-specific binaries
   - Install to `/opt/bzzz/`
   - Create symlinks in `/usr/local/bin/`

2. **System Setup**
   - Create `bzzz` system user
   - Setup directories (`/etc/bzzz`, `/var/log/bzzz`, `/var/lib/bzzz`)
   - Configure permissions

3. **Service Installation**
   - Systemd service files for BZZZ Go service and MCP server
   - Automatic startup configuration
   - Log rotation setup

### Phase 3: Web-Based Configuration
1. **Configuration Server**
   - Starts BZZZ service with minimal config
   - Launches React-based configuration UI
   - Accessible at `http://[node-ip]:8080/setup`

2. **8-Step Configuration Wizard**
   - System Detection & Validation
   - Network Configuration
   - Security Setup
   - AI Integration
   - Resource Allocation
   - Service Deployment
   - Cluster Formation
   - Testing & Validation

## Required User Information

### 1. Cluster Infrastructure
- **Network Configuration**
  - Subnet IP range (auto-detected, user can override)
  - Primary network interface selection
  - Port assignments (BZZZ: 8080, MCP: 3000, WebUI: 8080)
  - Firewall configuration preferences

### 2. Security Settings
- **SSH Key Management**
  - Generate new SSH keys
  - Upload existing keys
  - SSH username and port
  - Key distribution to cluster nodes

- **Authentication**
  - TLS/SSL certificate setup
  - Authentication method (token, OAuth2, LDAP)
  - Security policy configuration

### 3. AI Integration
- **OpenAI Configuration**
  - API key (secure input with validation)
  - Default model selection (GPT-5)
  - Cost limits (daily/monthly)
  - Usage monitoring preferences

- **Local AI Models**
  - Ollama/Parallama endpoint configuration
  - Model distribution strategy
  - GPU allocation for Parallama
  - Automatic model pulling

### 4. Resource Management
- **Hardware Allocation**
  - CPU cores allocation
  - Memory limits per service
  - Storage paths and quotas
  - GPU assignment (for Parallama)

- **Service Configuration**
  - Container resource limits
  - Auto-scaling policies
  - Monitoring and alerting
  - Backup and recovery

### 5. Cluster Topology
- **Node Roles**
  - Coordinator vs Worker designation
  - High availability setup
  - Load balancing configuration
  - Failover preferences

## Installation Flow

### Command Execution
```bash
curl -fsSL https://chorus.services/install.sh | sh
```

### Interactive Prompts
1. **GPU Detection Response**
   ```
   🚀 Multi-GPU Setup Detected (4 NVIDIA GPUs)
   Parallama is RECOMMENDED for optimal multi-GPU performance!
   
   Options:
   1. Install Parallama (recommended for GPU setups)
   2. Install standard Ollama  
   3. Skip Ollama installation (configure later)
   ```

2. **Installation Progress**
   ```
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   🔥 BZZZ Distributed AI Coordination Platform
      Installer v1.0
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   
   [INFO] Detected OS: Ubuntu 22.04
   [INFO] Detected architecture: amd64
   [SUCCESS] System requirements check passed
   [INFO] Detected 4 NVIDIA GPU(s)
   [SUCCESS] Dependencies installed successfully
   [SUCCESS] Parallama installed successfully
   [SUCCESS] BZZZ binaries installed successfully
   [SUCCESS] Configuration server started
   ```

3. **Completion Message**
   ```
   🚀 Next Steps:
   
   1. Complete your cluster configuration:
      👉 Open: http://192.168.1.100:8080/setup
   
   2. Useful commands:
      • Check status:      bzzz status
      • View logs:         sudo journalctl -u bzzz -f
      • Start/Stop:        sudo systemctl [start|stop] bzzz
   
   📚 Docs: https://docs.chorus.services/bzzz
   💬 Support: https://discord.gg/chorus-services
   ```

### Web Configuration Flow

#### Step 1: System Detection
- Display detected hardware configuration
- Show GPU setup and capabilities
- Validate software requirements
- System readiness check

#### Step 2: Network Configuration
- Network interface selection
- Subnet configuration
- Port assignment
- Firewall rule setup
- Connectivity testing

#### Step 3: Security Setup
- SSH key generation/upload
- TLS certificate configuration
- Authentication method selection
- Security policy setup

#### Step 4: AI Integration
- OpenAI API key configuration
- Model preferences and costs
- Ollama/Parallama setup
- Local model management

#### Step 5: Resource Allocation
- CPU/Memory allocation sliders
- Storage path configuration
- GPU assignment (Parallama)
- Resource monitoring setup

#### Step 6: Service Deployment
- Service configuration review
- Container deployment
- Health check setup
- Monitoring configuration

#### Step 7: Cluster Formation
- Create new cluster or join existing
- Network discovery
- Node role assignment
- Cluster validation

#### Step 8: Testing & Validation
- Connectivity tests
- AI model verification
- Performance benchmarks
- Configuration validation

## Files Structure

```
/home/tony/chorus/project-queues/active/BZZZ/install/
├── install.sh                           # Main installation script
├── config-ui/                          # React configuration interface
│   ├── package.json                    # Dependencies and scripts
│   ├── next.config.js                  # Next.js configuration
│   ├── tailwind.config.js              # Tailwind CSS config
│   ├── tsconfig.json                   # TypeScript config
│   ├── postcss.config.js               # PostCSS config
│   └── app/                            # Next.js app directory
│       ├── globals.css                 # Global styles
│       ├── layout.tsx                  # Root layout
│       ├── page.tsx                    # Home page (redirects to setup)
│       └── setup/
│           ├── page.tsx                # Main setup wizard
│           └── components/             # Setup step components
│               ├── SystemDetection.tsx
│               ├── NetworkConfiguration.tsx
│               ├── SecuritySetup.tsx
│               ├── AIConfiguration.tsx
│               ├── ResourceAllocation.tsx
│               ├── ServiceDeployment.tsx
│               ├── ClusterFormation.tsx
│               └── TestingValidation.tsx
├── requirements.md                      # Detailed requirements
└── INSTALLATION_SYSTEM.md             # This document
```

## Key Features

### 1. Intelligent GPU Detection
- Automatic detection of NVIDIA/AMD GPUs
- Multi-GPU topology analysis
- Recommends Parallama for multi-GPU setups
- Fallback to standard Ollama for single GPU
- CPU-only mode support

### 2. Comprehensive System Validation
- Hardware requirements checking
- Software dependency validation
- Network connectivity testing
- Security configuration verification

### 3. Production-Ready Setup
- Systemd service integration
- Proper user/permission management
- Log rotation and monitoring
- Security best practices
- Automatic startup configuration

### 4. Beautiful User Experience
- Modern React-based interface
- Progressive setup wizard
- Real-time validation feedback
- Mobile-responsive design
- Comprehensive help and documentation

### 5. Enterprise Features
- SSH key distribution
- TLS/SSL configuration
- LDAP/AD integration support
- Cost management and monitoring
- Multi-node cluster orchestration

## Next Implementation Steps

1. **Backend API Development**
   - Go-based configuration API
   - System detection endpoints
   - Configuration validation
   - Service management

2. **Enhanced Components**
   - Complete all setup step components
   - Real-time validation
   - Progress tracking
   - Error handling

3. **Cluster Management**
   - Node discovery protocols
   - Automated SSH setup
   - Service distribution
   - Health monitoring

4. **Security Hardening**
   - Certificate management
   - Secure key distribution
   - Network encryption
   - Access control

5. **Testing & Validation**
   - Integration test suite
   - Performance benchmarking
   - Security auditing
   - User acceptance testing

This installation system provides a seamless, professional-grade setup experience that rivals major infrastructure platforms while specifically optimizing for AI workloads and multi-GPU configurations.