# 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**:
```bash
# 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**:
```bash
# 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

```bash
# 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)

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

[control_center.server]
port = 9080

[services.gitea]
port = 3000

[services.surrealdb]
port = 8000
```

### Production (Multi-Host)

```toml
# 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

```yaml
services:
  orchestrator:
    ports:
      - "9090:9090"

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

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

  gitea:
    ports:
      - "3000:3000"
```

### Kubernetes

```yaml
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

```bash
# Allow orchestrator
sudo ufw allow 9090/tcp

# Allow control center
sudo ufw allow 9080/tcp

# Allow Gitea
sudo ufw allow 3000/tcp
```

### Production Server

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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