provisioning/config/default_ports.md

Provisioning Platform Default Ports

This document lists all default ports used by the Provisioning platform components.

Last Updated: 2025-10-09 Version: 2.0.5

---

Port Allocation Strategy

The platform uses the 90XX range for core services to avoid conflicts with common development tools and services.

Port Ranges

Range	Usage	Notes
9000-9099	Core Platform Services	Orchestrator, Control Center, APIs
5000-5999	Container & Registry Services	OCI Registry, DNS
3000-3999	Web UIs & External Services	Gitea, Frontend apps
8000-8999	Databases & Storage	SurrealDB, Redis, PostgreSQL

---

Core Platform Services (90XX Range)

Orchestrator

Default Port: 9090 Service: Provisioning Orchestrator Type: REST API Protocol: HTTP

Configuration:

• Code: provisioning/platform/orchestrator/src/lib.rs:79
• Config: provisioning/platform/orchestrator/config.defaults.toml:12
• Script: provisioning/platform/orchestrator/scripts/start-orchestrator.nu:5

Health Check: http://localhost:9090/health

Key Endpoints:

• Tasks: http://localhost:9090/tasks
• Workflows: http://localhost:9090/workflows/*
• Batch: http://localhost:9090/workflows/batch/*
• Test Environments: http://localhost:9090/test/environments/*

Override:

# CLI flag
./scripts/start-orchestrator.nu --port 8888

# Binary
./target/release/provisioning-orchestrator --port 8888

---

Control Center

Default Port: 9080 Service: Control Center (Authentication & Authorization) Type: REST API Protocol: HTTP

Configuration:

• Code: provisioning/platform/control-center/src/simple_config.rs:127
• Config: provisioning/platform/control-center/config.defaults.toml:18

Health Check: http://localhost:9080/health

Key Endpoints:

• Login: http://localhost:9080/auth/login
• Logout: http://localhost:9080/auth/logout
• Refresh: http://localhost:9080/auth/refresh
• Permissions: http://localhost:9080/permissions
• WebSocket: ws://localhost:9080/ws

Override:

# CLI flag
./target/release/control-center --port 8888

# Config file
[server]
port = 8888

---

API Gateway

Default Port: 9083 Service: API Gateway (Unified API Entry Point) Type: REST API Protocol: HTTP

Health Check: http://localhost:9083/health

---

MCP Server

Default Port: 9082 Service: Model Context Protocol Server Type: REST API Protocol: HTTP

Health Check: http://localhost:9082/health

---

Container & Registry Services (5XXX Range)

OCI Registry

Default Port: 5000 Service: OCI Registry (Extension Distribution) Type: Container Registry Protocol: HTTP

Health Check: http://localhost:5000/v2/

---

CoreDNS

Default Port: 5353 Service: CoreDNS (Internal DNS Resolution) Type: DNS Server Protocol: TCP/UDP

Health Check: dig @localhost -p 5353 provisioning.local

---

Web UIs & External Services (3XXX Range)

Gitea

Default Port: 3000 Service: Gitea (Git Server & Web UI) Type: Web UI Protocol: HTTP

Health Check: http://localhost:3000/api/healthz

---

Frontend Application

Default Port: 3001 Service: Control Center Frontend (React/Leptos) Type: Web UI Protocol: HTTP

---

Database & Storage Services (8XXX Range)

SurrealDB

Default Port: 8000 Service: SurrealDB (Main Database) Type: Database Protocol: WebSocket/HTTP

Health Check: http://localhost:8000/health

---

Redis

Default Port: 6379 Service: Redis (Cache & Session Store) Type: Cache/Database Protocol: Redis Protocol

Health Check: redis-cli ping

---

PostgreSQL

Default Port: 5432 Service: PostgreSQL (Optional Database) Type: Database Protocol: PostgreSQL Protocol

Health Check: pg_isready -h localhost -p 5432

---

Port Conflict Resolution

Common Conflicts

Port	Common Conflict	Provisioning Service	Resolution
8080	OrbStack, Jenkins, Tomcat	Orchestrator (moved to 9090)	Use 9090 instead
8081	Proxy services	Control Center (moved to 9080)	Use 9080 instead
3000	React dev servers	Gitea	Keep, rarely conflicts
5000	macOS AirPlay	OCI Registry	Disable AirPlay or change registry port
5353	Bonjour/mDNS	CoreDNS	Use alternate port for CoreDNS if needed

Checking Port Usage

# Check if port is in use
lsof -i :9090

# Find process using port
lsof -i :9090 | awk 'NR>1 {print $2}' | xargs ps -p

# Kill process on port
lsof -ti :9090 | xargs kill

# Check all provisioning ports
for port in 9090 9080 9082 9083 5000 5353 3000 8000; do
    echo "Port $port:" && lsof -i :$port || echo "  Free"
done

---

Environment-Specific Configuration

Development (Single Machine)

# config.dev.toml
[orchestrator.server]
port = 9090

[control_center.server]
port = 9080

[services.gitea]
port = 3000

[services.surrealdb]
port = 8000

Production (Multi-Host)

# config.prod.toml
[orchestrator.server]
host = "orchestrator.internal"
port = 9090

[control_center.server]
host = "auth.internal"
port = 9080

[services.oci_registry]
host = "registry.internal"
port = 5000

Docker Compose

services:
  orchestrator:
    ports:
      - "9090:9090"

  control-center:
    ports:
      - "9080:9080"

  oci-registry:
    ports:
      - "5000:5000"

  gitea:
    ports:
      - "3000:3000"

Kubernetes

apiVersion: v1
kind: Service
metadata:
  name: orchestrator
spec:
  type: ClusterIP
  ports:
    - port: 9090
      targetPort: 9090
      name: http
---
apiVersion: v1
kind: Service
metadata:
  name: control-center
spec:
  type: ClusterIP
  ports:
    - port: 9080
      targetPort: 9080
      name: http

---

Firewall Configuration

Development Machine

# Allow orchestrator
sudo ufw allow 9090/tcp

# Allow control center
sudo ufw allow 9080/tcp

# Allow Gitea
sudo ufw allow 3000/tcp

Production Server

# Orchestrator (internal only)
sudo ufw allow from 10.0.0.0/8 to any port 9090 proto tcp

# Control Center (internal + VPN)
sudo ufw allow from 10.0.0.0/8 to any port 9080 proto tcp

# OCI Registry (internal only)
sudo ufw allow from 10.0.0.0/8 to any port 5000 proto tcp

---

Troubleshooting

Port Already in Use

# Find what's using the port
lsof -i :9090

# Output example:
# COMMAND   PID  USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
# OrbStack  854  user  132u  IPv4 ...      0t0  TCP *:9090 (LISTEN)

# Stop the conflicting service
sudo systemctl stop orbstack  # Linux
# or
sudo launchctl stop com.orbstack  # macOS

# Or change provisioning port
./scripts/start-orchestrator.nu --port 9091

Health Checks Failing

# Check if service is running
ps aux | grep orchestrator

# Check if port is listening
netstat -an | grep 9090

# Test health endpoint
curl http://localhost:9090/health

# Check logs
tail -f ./data/orchestrator.log

Docker Port Conflicts

# List all container ports
docker ps --format "table {{.Names}}\t{{.Ports}}"

# Stop conflicting container
docker stop <container_name>

# Change port mapping in docker-compose.yml
services:
  orchestrator:
    ports:
      - "9091:9090"  # Host:Container

---

Quick Reference Table

Service	Port	Protocol	Health Check
Orchestrator	9090	HTTP	curl http://localhost:9090/health
Control Center	9080	HTTP	curl http://localhost:9080/health
API Gateway	9083	HTTP	curl http://localhost:9083/health
MCP Server	9082	HTTP	curl http://localhost:9082/health
OCI Registry	5000	HTTP	curl http://localhost:5000/v2/
CoreDNS	5353	DNS	dig @localhost -p 5353 provisioning.local
Gitea	3000	HTTP	curl http://localhost:3000/api/healthz
Frontend	3001	HTTP	curl http://localhost:3001
SurrealDB	8000	WS/HTTP	curl http://localhost:8000/health
Redis	6379	Redis	redis-cli ping
PostgreSQL	5432	PostgreSQL	pg_isready -h localhost -p 5432

---

Migration Notes

Port Changes History

Version	Service	Old Port	New Port	Reason
2.0.5	Orchestrator	8080	9090	OrbStack conflict
2.0.5	Control Center	8081/3000	9080	Standardization + conflict avoidance

Updating Existing Deployments

# 1. Update configuration
sed -i 's/:8080/:9090/g' config/*.toml
sed -i 's/:8081/:9080/g' config/*.toml

# 2. Rebuild services
cd provisioning/platform/orchestrator && cargo build --release
cd provisioning/platform/control-center && cargo build --release

# 3. Update systemd services (if used)
sudo sed -i 's/:8080/:9090/g' /etc/systemd/system/provisioning-orchestrator.service
sudo systemctl daemon-reload
sudo systemctl restart provisioning-orchestrator

# 4. Update firewall rules
sudo ufw delete allow 8080/tcp
sudo ufw allow 9090/tcp

# 5. Update reverse proxy (if used)
# Update nginx/traefik/etc configuration

---

Related Documentation

• Orchestrator API: docs/api/rest-api.md
• Control Center API: docs/api/rest-api.md#control-center-api
• Service Management: docs/user/SERVICE_MANAGEMENT_GUIDE.md
• Docker Deployment: provisioning/platform/docker-compose.yaml
• Kubernetes Deployment: provisioning/platform/k8s/

---

Maintained By: Platform Team Last Review: 2025-10-09 Next Review: 2026-01-09