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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

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

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

## Deployment Scenarios

### 1. Fresh Installation

```bash
# 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

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

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

### 3. Container Deployment

```dockerfile
# 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

```bash
# 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**
```bash
# 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**
```bash
# Check configuration status
./scripts/setup-transition.sh

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

**Port Conflicts**
```bash
# Check if port 8080 is in use
netstat -tulpn | grep 8080

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

### Debug Mode

```bash
# 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

```bash
# 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

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

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

# Validate configuration
bzzz --config-check
```

### Integration Testing

```bash
# 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](../docs/BZZZ-2B-ARCHITECTURE.md)
- [Operations Guide](../docs/BZZZv2B-OPERATIONS.md)
- [Developer Manual](../docs/BZZZv2B-DEVELOPER.md)