# Port Configuration Guide

## Overview

This document explains the port allocation strategy for development and test
environments.

## Development Environment (docker-compose.dev.yml)

### Services (External Ports 3000-3043 → Internal Port 8080)

- **Core Services**: 3000-3011
  - BFF: 3000
  - Conversation: 3001
  - AI: 3002
  - Auth: 3003
  - Content: 3004
  - Media: 3005
  - Notification: 3006
  - Moderation: 3007
  - RAG: 3008
  - TTS: 3009
  - STT: 3010
  - Ingestion: 3011

- **Additional Services**: 3012-3043
  - Knowledge: 3012
  - Observability: 3013
  - Anonymization: 3014
  - Audio-handoff: 3015
  - Auth-orchestrator: 3016
  - Catalog: 3017
  - Community-translation: 3018
  - Consent-management: 3019
  - Content-licensing: 3020
  - Content-verification: 3021
  - Data-governance: 3022
  - Error-handler: 3023
  - Group-meditation: 3024
  - Language-detection: 3025
  - Meditation-generation: 3026
  - Multi-region-resilience: 3027
  - Offline: 3028
  - Operational-excellence: 3029
  - Partner-api: 3030
  - Payment-orchestrator: 3031
  - Progress-sync: 3032
  - Real-time-sync: 3033
  - Rights-management: 3034
  - Safety-automation: 3035
  - Settlement: 3036
  - Spiritual-embeddings: 3037
  - Spiritual-guidance: 3038
  - Token-verification: 3039
  - User-preferences: 3040
  - Vectordb: 3041
  - Voice-pipeline: 3042
  - WebRTC: 3043

### Database Services

- **PostgreSQL**: 5433 → 5432
- **Milvus**: 19530 → 19530, 9091 → 9091
- **Redis**: 6380 → 6379
- **Elasticsearch**: 9201 → 9200, 9301 → 9300
- **Neo4j**: 7475 → 7474, 7688 → 7687
- **MinIO**: 9000 → 9000, 9001 → 9001
- **etcd**: 2379 → 2379

### Development Utilities

- **Nginx Proxy**: 8081 → 80
- **Prometheus**: 9090 → 9090
- **Grafana**: 9092 → 3000 (fixed from 9091 conflict)
- **Vault**: 8200 → 8200
- **Redis Commander**: 8082 → 8081
- **pgAdmin**: 8083 → 80
- **Jaeger**: 16686 → 16686, 14268 → 14268, 14250 → 14250, 6831/udp → 6831/udp,
  6832/udp → 6832/udp

## Test Environment (docker-compose.test.yml)

### Services (External Ports 8080-8123 → Internal Port 8080)

- **Core Services**: 8080-8092 (matches test expectations)
  - BFF: 8080
  - Conversation: 8081
  - AI: 8082
  - Auth: 8083
  - Content: 8084
  - Media: 8085
  - Notification: 8086
  - Moderation: 8087
  - RAG: 8088
  - TTS: 8089
  - STT: 8090
  - Ingestion: 8091
  - Knowledge: 8092

- **Additional Services**: 8093-8123
  - [Same services as dev environment, mapped to 8093-8123]

## Usage

### Development

```bash
# Start development environment with 3000-series ports
docker compose -f docker-compose.dev.yml up -d

# Access services at http://localhost:3000-3043
```

### Testing

```bash
# Start test environment with 8080-series ports
docker compose -f docker-compose.dev.yml -f docker-compose.test.yml up -d

# Access services at http://localhost:8080-8123
```

## Service Health Checks

All services implement health checks at `/health` or `/v1/health` endpoints:

```bash
# Check service health
curl http://localhost:3000/health  # Development
curl http://localhost:8080/health  # Test
```

## Environment Variables

You can override default ports using environment variables:

```bash
# Change BFF port in development
BFF_PORT=4000 docker compose -f docker-compose.dev.yml up -d
```

## Port Conflicts Resolution

1. **Fixed Grafana port conflict**: Changed from 9091 to 9092
2. **Separated test and dev environments**: Different port ranges prevent
   conflicts
3. **Database services**: Use standard ports on different host ports to avoid
   conflicts

## Service Discovery

Within the Docker network, services communicate using:

- Service names (e.g., `http://bff:8080`)
- Internal port 8080 for all services

## Networking

- **Development Network**: `lilith-dev`
- **Test Network**: `lilith-dev` (same network, different port mappings)
- **Internal Service Port**: 8080 (consistent across all services)
- **External Access**: Port mapped based on environment (3000-series for dev,
  8080-series for test)
