Update branding assets and deployment configurations
- Enhanced moebius ring logo design in Blender - Updated Docker Compose for website-only deployment with improved config - Enhanced teaser layout with updated branding integration - Added installation and setup documentation - Consolidated planning and reports documentation - Updated gitignore to exclude Next.js build artifacts and archives 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
tony
418
installer/INSTALLER_DOCUMENTATION.md
Normal file
418
installer/INSTALLER_DOCUMENTATION.md
Normal file
@@ -0,0 +1,418 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user