bzzz/archive/PORT_ASSIGNMENTS.md

# BZZZ Port Assignments

## Overview

BZZZ uses multiple ports for different services and operational modes. This document provides the official port assignments to avoid conflicts.

## Port Allocation

### Core BZZZ Services

| Port | Service | Mode | Description |
|------|---------|------|-------------|
| **8080** | Main HTTP API | Normal Operation | Primary BZZZ HTTP server with API endpoints |
| **8081** | Health & Metrics | Normal Operation | Health checks, metrics, and monitoring |
| **8090** | Setup Web UI | Setup Mode Only | Web-based configuration wizard |
| **4001** | P2P Network | Normal Operation | libp2p networking and peer communication |

### Additional Services

| Port | Service | Context | Description |
|------|---------|---------|-------------|
| **3000** | MCP Server | Development | Model Context Protocol server |
| **11434** | Ollama | AI Models | Local AI model runtime (if installed) |

## Port Usage by Mode

### Setup Mode (No Configuration)
- **8090**: Web configuration interface
  - Accessible at `http://localhost:8090`
  - Serves embedded React setup wizard
  - API endpoints at `/api/setup/*`
  - Auto-redirects to setup flow

### Normal Operation Mode (Configured)
- **8080**: Main HTTP API server
  - Health check: `http://localhost:8080/api/health`
  - Status endpoint: `http://localhost:8080/api/status`
  - Hypercore logs: `http://localhost:8080/api/hypercore/*`
- **8081**: Health and metrics server
  - Health endpoint: `http://localhost:8081/health`
  - Metrics endpoint: `http://localhost:8081/metrics`
- **4001**: P2P networking (libp2p)

## Port Selection Rationale

### 8090 for Setup UI
- **Chosen**: Port 8090 for setup web interface
- **Reasoning**: 
  - Avoids conflict with normal BZZZ operation (8080)
  - Not in common use on development systems
  - Sequential and memorable (8090 = setup, 8080 = normal)
  - Outside common service ranges (3000-3999, 8000-8099)

### Port Conflict Avoidance
Current system analysis shows these ports are already in use:
- 8080: Main BZZZ API (normal mode)
- 8081: Health/metrics server
- 8088: Other system service
- 3333: System service
- 3051: AnythingLLM
- 3030: System service

Port 8090 is confirmed available and reserved for BZZZ setup mode.

## Configuration Examples

### Enhanced Installer Configuration
```yaml
# Generated by install-chorus-enhanced.sh
api:
  host: "0.0.0.0"
  port: 8080

health:
  port: 8081
  enabled: true

p2p:
  port: 4001
  discovery:
    enabled: true
```

### Web UI Access URLs

#### Setup Mode
```bash
# When no configuration exists
http://localhost:8090           # Setup wizard home
http://localhost:8090/setup/    # Setup flow
http://localhost:8090/api/health # Setup health check
```

#### Normal Mode
```bash
# After configuration is complete
http://localhost:8080/api/health  # Main health check
http://localhost:8080/api/status  # BZZZ status
http://localhost:8081/health      # Dedicated health service
http://localhost:8081/metrics     # Prometheus metrics
```

## Network Security Considerations

### Firewall Rules
```bash
# Allow BZZZ setup (temporary, during configuration)
sudo ufw allow 8090/tcp comment "BZZZ Setup UI"

# Allow BZZZ normal operation
sudo ufw allow 8080/tcp comment "BZZZ HTTP API"
sudo ufw allow 8081/tcp comment "BZZZ Health/Metrics"
sudo ufw allow 4001/tcp comment "BZZZ P2P Network"
```

### Production Deployment
- Setup port (8090) should be blocked after configuration
- Main API (8080) should be accessible to cluster nodes
- P2P port (4001) must be open for cluster communication
- Health port (8081) should be accessible to monitoring systems

## Integration with Existing Systems

### CHORUS Cluster Integration
```bash
# Standard CHORUS deployment ports
# BZZZ: 8080 (main), 8081 (health), 4001 (p2p)
# WHOOSH: 3001 (web interface)
# Ollama: 11434 (AI models)
# GITEA: 3000 (repository)
```

### Docker Swarm Deployment
```yaml
# docker-compose.swarm.yml
services:
  bzzz:
    ports:
      - "8080:8080"  # Main API
      - "8081:8081"  # Health/Metrics
      - "4001:4001"  # P2P Network
    # Setup port (8090) not exposed in production
```

## Troubleshooting

### Port Conflicts
```bash
# Check if ports are available
netstat -tuln | grep -E ':(8080|8081|8090|4001)'

# Find process using a port
lsof -i :8090

# Kill process if needed
sudo kill $(lsof -t -i:8090)
```

### Service Validation
```bash
# Test setup mode availability
curl -s http://localhost:8090/api/health

# Test normal mode availability
curl -s http://localhost:8080/api/health

# Test P2P port (should show connection refused when working)
telnet localhost 4001
```

## Migration Notes

### From Previous Versions
- Old setup configurations using port 8082 will automatically migrate to 8090
- Integration tests updated to use new port assignments
- Documentation updated across all references

### Backward Compatibility
- Enhanced installer script generates correct port assignments
- Existing configurations continue to work
- New installations use documented port scheme

## Summary

**BZZZ Port Assignments:**
- **8090**: Setup Web UI (temporary, configuration mode only)
- **8080**: Main HTTP API (normal operation)
- **8081**: Health & Metrics (normal operation)  
- **4001**: P2P Network (cluster communication)

This allocation ensures no conflicts with existing services while providing clear separation between setup and operational modes.