bzzz/install/SETUP_INTEGRATION_GUIDE.md

BZZZ Web Configuration Setup Integration Guide

This guide explains how to use the new integrated web-based configuration system for BZZZ.

Overview

BZZZ now includes an embedded web configuration interface that automatically activates when:

• No configuration file exists
• The existing configuration is invalid or incomplete
• Setup is explicitly required

Features

🎯 Automatic Setup Detection

• BZZZ automatically detects when setup is required on startup
• No separate installation or configuration needed
• Seamless transition from setup to normal operation

🌐 Embedded Web Interface

• Complete React-based setup wizard embedded in the Go binary
• No external dependencies required
• Works offline and in air-gapped environments

🔧 Comprehensive Configuration

• System detection and hardware analysis
• Repository integration (GitHub, GitLab, Gitea)
• Network and security configuration
• AI model and capability setup
• Service deployment options

Quick Start

1. Build BZZZ with Embedded UI

# Build the complete system with embedded web UI
make build

# Or build just the binary (uses placeholder UI)
make build-go

2. First-Time Setup

# Start BZZZ - it will automatically enter setup mode
./build/bzzz

# Or use the transition script for guided setup
./scripts/setup-transition.sh

3. Access Setup Interface

Open your browser to: http://localhost:8080

The setup wizard will guide you through:

1. System Detection - Hardware and environment analysis
2. Agent Configuration - ID, capabilities, and AI models
3. Repository Setup - Git integration configuration
4. Network Configuration - P2P and cluster settings
5. Security Setup - Encryption and access control
6. Service Deployment - Additional services configuration
7. Testing & Validation - Configuration verification

4. Complete Setup

After saving configuration:

1. BZZZ will create the configuration file
2. Restart BZZZ to enter normal operation mode
3. The web interface will no longer be available

Development Workflow

Building the Web UI

# Install dependencies
make deps

# Build just the web UI
make build-ui

# Embed web UI in Go binary
make embed-ui

# Complete build process
make build

Development Mode

# Start both React dev server and Go API
make dev

# React UI: http://localhost:3000
# Go API: http://localhost:8080

Project Structure

BZZZ/
├── install/config-ui/          # React setup wizard
│   ├── app/                    # Next.js application
│   ├── package.json            # Node.js dependencies
│   └── next.config.js          # Build configuration
├── pkg/web/                    # Embedded file system
│   ├── embed.go                # File embedding logic
│   └── index.html              # Fallback page
├── api/                        # Go HTTP server
│   ├── http_server.go          # Main server with setup routes
│   └── setup_manager.go        # Setup logic
├── Makefile                    # Build automation
└── scripts/
    └── setup-transition.sh     # Setup helper script

Configuration Management

Configuration Files

• Default Location: ~/.bzzz/config.yaml
• Environment Override: BZZZ_CONFIG_PATH
• Backup Directory: ~/.bzzz/backups/

Setup Requirements Detection

BZZZ checks for setup requirements using:

1. Configuration file existence
2. Configuration file validity
3. Essential fields completion (Agent ID, capabilities, models)

Configuration Validation

The setup system validates:

• Required fields presence
• Repository connectivity
• AI model availability
• Network configuration
• Security settings

API Endpoints

Setup Mode APIs

When in setup mode, BZZZ exposes these endpoints:

# Check if setup is required
GET /api/setup/required

# Get system information
GET /api/setup/system

# Validate repository configuration
POST /api/setup/repository/validate

# Get supported repository providers
GET /api/setup/repository/providers

# Validate complete configuration
POST /api/setup/validate

# Save configuration
POST /api/setup/save

# Health check
GET /api/health

Web UI Routes

# Setup interface (embedded React app)
GET /
GET /setup
GET /setup/*

# API proxy (development only)
/api/* -> http://localhost:8080/api/*

Deployment Scenarios

1. Fresh Installation

# Build and start BZZZ
make build
./build/bzzz

# Access setup at http://localhost:8080
# Complete configuration wizard
# Restart BZZZ for normal operation

2. Existing Installation

# Backup existing configuration
./scripts/setup-transition.sh

# BZZZ will use existing config if valid
# Or enter setup mode if invalid

3. Container Deployment

# Build container with embedded UI
FROM golang:1.21-alpine AS builder
COPY . /app
WORKDIR /app
RUN make build

FROM alpine:latest
COPY --from=builder /app/build/bzzz /usr/local/bin/
EXPOSE 8080
CMD ["bzzz"]

4. Cluster Deployment

# Build BZZZ with embedded UI
make build

# Deploy to each cluster node
scp build/bzzz node1:/usr/local/bin/
ssh node1 'bzzz'  # Setup via web interface

# Repeat for additional nodes
# Nodes will discover each other via mDNS

Troubleshooting

Common Issues

Web UI Not Loading

# Check if web UI was built
make build-ui

# Verify embedded files
ls -la pkg/web/

# Rebuild if necessary
make clean && make build

Setup Not Starting

# Check configuration status
./scripts/setup-transition.sh

# Force setup mode by removing config
rm ~/.bzzz/config.yaml
./build/bzzz

Port Conflicts

# Check if port 8080 is in use
netstat -tulpn | grep 8080

# Kill conflicting processes
sudo lsof -ti:8080 | xargs kill -9

Debug Mode

# Enable debug logging
export BZZZ_LOG_LEVEL=debug
./build/bzzz

# Check embedded files
curl http://localhost:8080/api/health

Security Considerations

Network Security

• Setup interface only accessible on localhost by default
• CORS enabled for development, restricted in production
• HTTPS recommended for external access

Configuration Security

• Sensitive values (tokens, keys) stored in separate files
• Configuration backups created automatically
• Audit logging for configuration changes

Access Control

• Setup mode automatically disabled after configuration
• No authentication required for initial setup
• Full authentication required for normal operation

Advanced Usage

Custom Build Configuration

# Build with custom UI path
UI_DIR=custom-ui make build

# Build without UI (API only)
make build-go

# Production build with optimizations
NODE_ENV=production make build

Configuration Migration

# Export existing configuration
bzzz --export-config > backup.yaml

# Import configuration
bzzz --import-config backup.yaml

# Validate configuration
bzzz --config-check

Integration Testing

# Test complete setup flow
make test

# Test web UI components
cd install/config-ui && npm test

# Test Go integration
go test ./api/...

Next Steps

After completing setup:

1. Verify Operation: Check BZZZ logs and peer connections
2. Configure Repositories: Add GitHub/GitLab tokens and repositories
3. Join Cluster: Configure additional nodes to join the cluster
4. Monitor Health: Use /api/health endpoint for monitoring
5. Scale Services: Deploy additional BZZZ components as needed

For advanced configuration and cluster management, see:

• BZZZ Architecture Documentation
• Operations Guide
• Developer Manual