chorus-services/installer/INSTALLER_DOCUMENTATION.md

# CHORUS Enhanced Installer Documentation

## Overview

The CHORUS Enhanced Installer (`install-chorus-enhanced.sh`) provides a complete one-command installation solution for the CHORUS distributed AI orchestration platform, addressing the critical gap between binary installation and functional repository configuration.

## Key Features

### 🎯 Complete End-to-End Setup
- **Binary Installation**: Downloads and installs BZZZ P2P coordination agent
- **Repository Integration**: Full GITEA/GitHub configuration with credential management
- **Service Management**: SystemD service installation and configuration
- **Infrastructure Setup**: Ollama AI models and coordinator components

### 🔧 Repository Provider Support
- **GITEA Integration**: Auto-detection of local GITEA instances
- **GitHub Support**: Full GitHub API integration
- **Unified Configuration**: Single YAML config for both providers
- **Credential Management**: Secure token storage and validation

### 🚀 Installation Modes
- **Worker Node**: Standard agent installation
- **Coordinator Node**: Additional components (Docker, Age encryption, WHOOSH)
- **Custom Configuration**: Interactive setup with sensible defaults

## Installation Methods

### Quick Install (Recommended)
```bash
curl -fsSL https://chorus.services/install-enhanced.sh | sh
```

### With Options
```bash
curl -fsSL https://chorus.services/install-enhanced.sh | sh -s -- --coordinator --models "llama3.2,qwen2.5:7b"
```

### Advanced Configuration
```bash
curl -fsSL https://chorus.services/install-enhanced.sh | sh -s -- --gitea-url "https://git.mycompany.com" --github
```

## Command Line Options

| Option | Description | Default |
|--------|-------------|---------|
| `--coordinator` | Install as cluster coordinator | false |
| `--models MODEL` | Comma-separated AI models to install | none |
| `--skip-deps` | Skip dependency installation | false |
| `--quiet` | Minimal output mode | false |
| `--github` | Use GitHub instead of GITEA | gitea |
| `--gitea-url URL` | Custom GITEA instance URL | http://ironwood:3000 |
| `--help` | Show help information | - |

## Repository Configuration

### GITEA Setup (Default)
```yaml
repository:
  provider: "gitea"
  config:
    base_url: "http://ironwood:3000"
    owner: "tony"
    repository: "bzzz"
    task_label: "bzzz-task"
    in_progress_label: "bzzz-working"
    completed_label: "bzzz-completed"
    priority_label: "bzzz-priority"
    assignee: "tony"
    base_branch: "main"
    branch_prefix: "bzzz/task-"
    token_file: "/home/user/chorus/business/secrets/gitea-token"
```

### GitHub Setup
```yaml
repository:
  provider: "github"
  config:
    base_url: "https://api.github.com"
    owner: "username"
    repository: "project"
    task_label: "bzzz-task"
    token_file: "/home/user/chorus/business/secrets/gh-token"
```

## Installation Process

### Phase 1: System Detection
1. **OS Detection**: Linux (apt/yum/pacman) or macOS (brew)
2. **Architecture Detection**: amd64, arm64, armv7
3. **Dependency Check**: curl, git, jq installation
4. **GITEA Discovery**: Auto-detect local instances

### Phase 2: Credential Setup
1. **Token Management**: Secure storage in `~/chorus/business/secrets/`
2. **Repository Access**: Interactive token configuration
3. **Access Validation**: Test API connectivity
4. **Permission Verification**: Ensure required scopes

### Phase 3: Infrastructure Installation
1. **Ollama Setup**: AI model runtime installation
2. **Directory Structure**: CHORUS workspace creation
3. **Binary Download**: Architecture-specific BZZZ binary
4. **Service Files**: SystemD configuration generation

### Phase 4: BZZZ Configuration
1. **Node Configuration**: Interactive hostname, role, ports
2. **Repository Integration**: Complete YAML generation
3. **Agent Settings**: Capabilities and expertise configuration
4. **Security Setup**: Encryption and audit logging

### Phase 5: Service Installation
1. **SystemD Integration**: Service file installation
2. **Service Activation**: Enable and start BZZZ
3. **Health Verification**: Service status validation
4. **Coordinator Setup**: Additional components if needed

## Generated Configuration

### Complete BZZZ YAML Configuration
```yaml
# Node Identity
node:
  id: "hostname"
  role: "worker|coordinator"

# API Configuration
api:
  host: "0.0.0.0"
  port: 8080

# Health Monitoring
health:
  port: 8081
  enabled: true

# P2P Networking
p2p:
  port: 4001
  discovery:
    enabled: true
    bootstrap_nodes: []
    service_tag: "bzzz-peer-discovery"
  topics:
    bzzz: "bzzz/coordination/v1"
    hmmm: "hmmm/meta-discussion/v1"

# Agent Configuration
agent:
  id: "hostname-agent"
  capabilities: ["general", "reasoning", "task-coordination"]
  poll_interval: "30s"
  max_tasks: 3
  specialization: "general_developer"
  role: "Full Stack Engineer"
  expertise: ["golang", "typescript", "docker", "kubernetes"]

# Repository Integration (CORE FEATURE)
repository:
  provider: "gitea|github"
  config:
    base_url: "provider-url"
    owner: "repository-owner"
    repository: "repository-name"
    task_label: "bzzz-task"
    token_file: "path-to-token"

# Security Configuration
security:
  admin_key_shares:
    threshold: 3
    total_shares: 5
  election_config:
    heartbeat_timeout: "5s"
    discovery_timeout: "30s"
    election_timeout: "15s"
    minimum_quorum: 3
  key_rotation_days: 90
  audit_logging: true

# Storage and Logging
storage:
  path: "$HOME/.chorus/data"
  type: "filesystem"

logging:
  level: "info"
  format: "text"
  output: "stdout"
  file: "$HOME/.chorus/logs/bzzz.log"
```

## Service Management

### SystemD Service Configuration
```ini
[Unit]
Description=BZZZ P2P Task Coordination System
Documentation=https://chorus.services/docs/bzzz
After=network.target
Wants=network.target

[Service]
Type=simple
User=username
Group=username
WorkingDirectory=/path/to/bzzz
ExecStart=/path/to/bzzz --config /path/to/config/bzzz.yaml
Restart=always
RestartSec=10

# Security Settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=false

[Install]
WantedBy=multi-user.target
```

### Service Commands
```bash
# Service Management
sudo systemctl status bzzz        # Check status
sudo systemctl restart bzzz       # Restart service
sudo journalctl -u bzzz -f        # Follow logs

# Health Monitoring
curl http://localhost:8081/health  # Health check
curl http://localhost:8081/metrics # Metrics
curl http://localhost:8080         # API endpoint
```

## API Endpoints

### Health and Monitoring
- `GET /health` - Service health status
- `GET /metrics` - Prometheus metrics
- `GET /status` - Agent status and active tasks

### Task Coordination
- Task discovery handled automatically via repository polling
- Task claiming through repository provider APIs
- Progress updates via repository comments/labels

## Security Features

### Credential Management
- **Token Storage**: Secure file permissions (600)
- **API Validation**: Repository access verification
- **Encryption**: Age keys for coordinator nodes
- **Audit Logging**: Security event tracking

### Network Security
- **P2P Encryption**: libp2p secure channels
- **API Authentication**: Repository token validation
- **Local Binding**: Services bound to localhost by default

## Installation Verification

### Automatic Checks
1. **Service Status**: BZZZ systemd service active
2. **Configuration**: Valid YAML configuration file
3. **Repository Access**: API connectivity test
4. **Ollama Status**: AI runtime availability

### Manual Verification
```bash
# Check all services
systemctl status bzzz ollama

# Test API endpoints
curl http://localhost:8081/health
curl http://localhost:8080/status

# View configuration
cat ~/chorus/project-queues/active/BZZZ/config/bzzz.yaml

# Check logs
sudo journalctl -u bzzz --since "1 hour ago"
```

## Troubleshooting

### Common Issues

#### Service Not Starting
```bash
# Check logs
sudo journalctl -u bzzz -f

# Verify binary
~/chorus/project-queues/active/BZZZ/bzzz --version

# Check configuration
cat ~/chorus/project-queues/active/BZZZ/config/bzzz.yaml
```

#### Repository Access Issues
```bash
# Verify token file
ls -la ~/chorus/business/secrets/

# Test API access manually
curl -H "Authorization: token $(cat ~/chorus/business/secrets/gitea-token)" \
     http://ironwood:3000/api/v1/user
```

#### Network Connectivity
```bash
# Check port availability
netstat -tlnp | grep :8080
netstat -tlnp | grep :8081

# Test P2P connectivity
netstat -tlnp | grep :4001
```

## Coordinator Features

### Additional Components
- **Docker**: Container runtime for WHOOSH dashboard
- **Age Encryption**: Cryptographic key management
- **WHOOSH Integration**: Web-based cluster management
- **Bootstrap Node**: P2P network discovery

### Setup Process
```bash
# Install as coordinator
curl -fsSL https://chorus.services/install-enhanced.sh | sh -s -- --coordinator

# Additional coordinator tasks
docker-compose up -d whoosh  # Start dashboard
age-keygen -o secrets/key    # Generate encryption keys
```

## Architecture Integration

### CHORUS Ecosystem
- **BZZZ**: P2P task coordination agent
- **WHOOSH**: Web-based cluster dashboard
- **Ollama**: Local AI model runtime
- **Repository Provider**: Task source (GITEA/GitHub)

### Data Flow
1. **Task Discovery**: Repository polling for labeled issues
2. **Task Claiming**: Atomic assignment via API
3. **Work Execution**: Local processing with progress updates
4. **Task Completion**: Results submission and issue closure

## Migration and Updates

### From Previous Versions
- Configuration migration handled automatically
- Service restart required for updates
- Backward compatibility with existing repositories

### Update Process
```bash
# Download new installer
curl -fsSL https://chorus.services/install-enhanced.sh > install.sh

# Run update (preserves configuration)
chmod +x install.sh && ./install.sh
```

## Performance and Scaling

### Resource Requirements
- **CPU**: 1-2 cores minimum
- **Memory**: 2GB RAM minimum
- **Storage**: 10GB for binaries, models, and logs
- **Network**: Stable internet for repository access

### Scaling Considerations
- **Worker Nodes**: Add with same installer
- **Load Balancing**: Automatic via P2P discovery
- **High Availability**: Multi-coordinator setup supported

## Integration Points

### Repository Providers
- **GITEA**: Self-hosted Git service
- **GitHub**: Cloud-based Git service
- **Custom**: Extensible provider architecture

### AI Models
- **Ollama Integration**: Local model runtime
- **Model Management**: Automatic pulling and updates
- **Custom Models**: Support for specialized models

### Monitoring
- **SystemD**: Native service monitoring
- **Health Endpoints**: HTTP health checks
- **Metrics**: Prometheus-compatible metrics
- **Logs**: Structured logging to journald

## Comparison with Basic Installer

### Enhanced Features (install-chorus-enhanced.sh)
✅ **Repository Configuration**: Complete GITEA/GitHub setup  
✅ **Credential Management**: Secure token storage  
✅ **API Validation**: Repository access verification  
✅ **YAML Configuration**: Complete config generation  
✅ **Interactive Setup**: User-friendly configuration  
✅ **Auto-detection**: GITEA instance discovery  
✅ **Provider Switching**: GitHub/GITEA selection  

### Basic Installer Limitations (install-chorus.sh)
❌ **No Repository Setup**: Manual configuration required  
❌ **No Credentials**: Token management missing  
❌ **JSON Config**: Basic configuration only  
❌ **No Validation**: No API connectivity testing  
❌ **Manual Setup**: Requires post-install configuration  

This enhanced installer completely addresses the critical gap identified during deployment, providing a truly seamless installation experience from download to functional task coordination.