bzzz/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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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.