Save current BZZZ config-ui state before CHORUS branding update

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

PORT_ASSIGNMENTS.md

@@ -0,0 +1,191 @@
+# 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.