chorus-services/installer/README.md

CHORUS Installer & Release System

This directory contains the complete installer and release build system for CHORUS.

Files Overview

Installer System

• install-chorus.sh - Main CLI installer script (like Ollama)
• chorus-services-landing.html - Landing page for chorus.services website

Build System

• build-release.sh - Comprehensive cross-platform build system
• build-bzzz-minimal.sh - Minimal BZZZ builder (avoids import cycles)
• deploy-releases.sh - Deploy built binaries to release servers

Quick Start

1. Build Binaries

For a quick minimal build (recommended):

./build-bzzz-minimal.sh

For full cross-platform build:

./build-release.sh

2. Deploy Locally for Testing

./deploy-releases.sh --target local

This creates a local HTTP server at http://localhost:8000 and generates install-chorus-local.sh for testing.

3. Test the Installer

Start the local release server:

cd ~/chorus/local-releases && ./serve.sh

In another terminal, test the installer:

./install-chorus-local.sh --coordinator --skip-deps

4. Deploy to Production

./deploy-releases.sh --target production

Architecture

Binary Distribution URLs

The installer expects these URLs to be available:

• https://releases.chorus.services/bzzz/latest/bzzz-linux-amd64
• https://releases.chorus.services/bzzz/latest/bzzz-darwin-amd64
• https://releases.chorus.services/bzzz/latest/bzzz-linux-arm64
• https://releases.chorus.services/bzzz/latest/bzzz.service
• https://releases.chorus.services/bzzz/latest/install-service.sh
• https://releases.chorus.services/whoosh/latest/whoosh-docker-compose.tar.gz

Supported Platforms

• Linux AMD64 (x86_64)
• Linux ARM64 (aarch64)
• Linux ARM (armv7)
• macOS AMD64 (Intel)
• macOS ARM64 (Apple Silicon)

Features

CLI Installer Features

• ✅ One-command installation like Ollama
• ✅ Cross-platform support (Linux, macOS)
• ✅ Pre-built binary distribution
• ✅ Automatic dependency detection
• ✅ Coordinator vs worker node setup
• ✅ AI model installation
• ✅ Systemd service setup
• ✅ Age encryption key generation
• ✅ Graceful error handling

Build System Features

• ✅ Cross-platform binary builds
• ✅ Minimal BZZZ builder (avoids import cycles)
• ✅ Automatic checksums
• ✅ Release versioning
• ✅ Service file generation
• ✅ Install script creation

Deployment Features

• ✅ Local development server
• ✅ Production deployment
• ✅ Docker Swarm deployment
• ✅ Automatic URL updates for testing

Usage Examples

Build and deploy for local testing:

./build-bzzz-minimal.sh
./deploy-releases.sh --target local
cd ~/chorus/local-releases && ./serve.sh &
./install-chorus-local.sh --coordinator

Build specific version:

VERSION=v1.0.0 ./build-bzzz-minimal.sh
./deploy-releases.sh --target production --channel v1.0.0

Deploy to Docker Swarm:

./deploy-releases.sh --target swarm

Benefits

For Users

• Simple one-command installation
• No need to install development tools
• Fast download and setup
• Cross-platform compatibility

For Developers

• Protected source code
• Controlled licensing
• Version management
• Easy testing and deployment

For Business

• Professional distribution
• Licensing control
• Usage analytics potential
• Brand consistency

Troubleshooting

If BZZZ build fails with import cycles:

Use the minimal builder:

./build-bzzz-minimal.sh

This creates a basic HTTP server that provides the API endpoints needed by WHOOSH and other components.

If installer can't download binaries:

1. Check if local server is running: curl http://localhost:8000/bzzz/latest/bzzz-linux-amd64
2. Use the local installer: ./install-chorus-local.sh
3. Check deployment logs

If service won't start:

1. Check binary permissions: ls -la ~/chorus/project-queues/active/BZZZ/bzzz
2. Test binary manually: ~/chorus/project-queues/active/BZZZ/bzzz --version
3. Check service logs: sudo journalctl -u bzzz -f

Next Steps

1. Set up releases.chorus.services - Host the release files
2. Automate builds - CI/CD pipeline for automatic releases
3. Add telemetry - Track installer usage and success rates
4. Expand platforms - Windows support, additional architectures
5. Package managers - Homebrew, APT, etc.