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)

curl -fsSL https://chorus.services/install-enhanced.sh | sh

With Options

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

Advanced Configuration

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)

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

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

# 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

[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

# 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

# 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

# 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

# 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

# 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

# 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

# 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.