Major updates and improvements to BZZZ system
- Updated configuration and deployment files - Improved system architecture and components - Enhanced documentation and testing - Fixed various issues and added new features 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
anthonyrawlins
355
deployments/bare-metal/SETUP_INTEGRATION_GUIDE.md
Normal file
355
deployments/bare-metal/SETUP_INTEGRATION_GUIDE.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user