Phase 10.2: Complete Docker Compose Configuration and Deployment Documentation

## 📋 Task Description

Create comprehensive Docker Compose configuration for local development and testing that orchestrates all StarGate components (API/Worker, MongoDB, Redis, RabbitMQ). Include environment-specific configurations, networking, volumes, health checks, and complete deployment documentation.

## 🎯 Objectives

- Complete docker-compose.yml with all services
- Create environment-specific compose files (dev, prod)
- Configure service networking and dependencies
- Setup persistent volumes for data
- Configure health checks for all services
- Add service restart policies
- Create environment variable templates
- Document deployment procedures
- Create deployment scripts
- Test complete stack startup
- Verify service communication
- Document troubleshooting procedures

## 📦 Deliverables

### 1. Create Main Docker Compose File

Create `docker-compose.yml`:

```yaml
version: '3.8'

services:
  # ============================================
  # MongoDB - Document Database
  # ============================================
  mongodb:
    image: mongo:7.0
    container_name: stargate-mongodb
    restart: unless-stopped
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD:-admin123}
      MONGO_INITDB_DATABASE: stargate
    volumes:
      - mongodb-data:/data/db
      - mongodb-config:/data/configdb
      - ./scripts/mongo-init.js:/docker-entrypoint-initdb.d/mongo-init.js:ro
    networks:
      - stargate-network
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  # ============================================
  # Redis - Cache & Session Store
  # ============================================
  redis:
    image: redis:7.2-alpine
    container_name: stargate-redis
    restart: unless-stopped
    ports:
      - "6379:6379"
    command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD:-redis123}
    volumes:
      - redis-data:/data
    networks:
      - stargate-network
    healthcheck:
      test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  # ============================================
  # RabbitMQ - Message Broker
  # ============================================
  rabbitmq:
    image: rabbitmq:3.13-management-alpine
    container_name: stargate-rabbitmq
    restart: unless-stopped
    ports:
      - "5672:5672"   # AMQP
      - "15672:15672" # Management UI
    environment:
      RABBITMQ_DEFAULT_USER: ${RABBITMQ_USER:-guest}
      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD:-guest}
      RABBITMQ_DEFAULT_VHOST: stargate
    volumes:
      - rabbitmq-data:/var/lib/rabbitmq
      - ./config/rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf:ro
    networks:
      - stargate-network
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "ping"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  # ============================================
  # StarGate Server (API + Worker)
  # ============================================
  stargate-server:
    build:
      context: .
      dockerfile: src/StarGate.Server/Dockerfile
      args:
        BUILD_DATE: ${BUILD_DATE}
        VCS_REF: ${VCS_REF}
    image: stargate/stargate-server:${VERSION:-latest}
    container_name: stargate-server
    restart: unless-stopped
    ports:
      - "8080:8080" # API
      - "8081:8081" # Metrics
    environment:
      ASPNETCORE_ENVIRONMENT: ${ASPNETCORE_ENVIRONMENT:-Development}
      ASPNETCORE_URLS: http://+:8080
      
      # MongoDB Configuration
      MongoDB__ConnectionString: mongodb://admin:${MONGO_PASSWORD:-admin123}@mongodb:27017/stargate?authSource=admin
      MongoDB__DatabaseName: stargate
      
      # Redis Configuration
      Redis__ConnectionString: redis:6379,password=${REDIS_PASSWORD:-redis123}
      
      # RabbitMQ Configuration
      RabbitMQ__HostName: rabbitmq
      RabbitMQ__Port: 5672
      RabbitMQ__VirtualHost: stargate
      RabbitMQ__UserName: ${RABBITMQ_USER:-guest}
      RabbitMQ__Password: ${RABBITMQ_PASSWORD:-guest}
      
      # Resilience Configuration
      Resilience__Retry__MaxRetryAttempts: 3
      Resilience__CircuitBreaker__FailureThreshold: 0.5
      Resilience__CircuitBreaker__BreakDurationSeconds: 30
      Resilience__Timeout__DatabaseTimeoutSeconds: 30
      
      # Logging
      Logging__LogLevel__Default: Information
      Logging__LogLevel__Microsoft.AspNetCore: Warning
      Logging__LogLevel__StarGate: Debug
    volumes:
      - stargate-logs:/app/logs
      # Optional: Mount appsettings for override
      # - ./appsettings.Production.json:/app/appsettings.Production.json:ro
    networks:
      - stargate-network
    depends_on:
      mongodb:
        condition: service_healthy
      redis:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 40s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

networks:
  stargate-network:
    driver: bridge
    name: stargate-network

volumes:
  mongodb-data:
    name: stargate-mongodb-data
  mongodb-config:
    name: stargate-mongodb-config
  redis-data:
    name: stargate-redis-data
  rabbitmq-data:
    name: stargate-rabbitmq-data
  stargate-logs:
    name: stargate-logs
```

### 2. Create Development Override

Create `docker-compose.override.yml`:

```yaml
version: '3.8'

# Development-specific configuration
# Automatically merged with docker-compose.yml when running docker-compose up

services:
  stargate-server:
    build:
      target: runtime
    environment:
      ASPNETCORE_ENVIRONMENT: Development
      Logging__LogLevel__StarGate: Debug
      Logging__LogLevel__Microsoft.EntityFrameworkCore: Information
    volumes:
      # Hot reload for development (if using dotnet watch)
      - ./src:/src:ro
    # Override restart policy for dev
    restart: "no"

  # Add development tools
  mongo-express:
    image: mongo-express:latest
    container_name: stargate-mongo-express
    restart: unless-stopped
    ports:
      - "8082:8081"
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: ${MONGO_PASSWORD:-admin123}
      ME_CONFIG_MONGODB_URL: mongodb://admin:${MONGO_PASSWORD:-admin123}@mongodb:27017/
      ME_CONFIG_BASICAUTH_USERNAME: admin
      ME_CONFIG_BASICAUTH_PASSWORD: admin
    networks:
      - stargate-network
    depends_on:
      - mongodb
```

### 3. Create Production Configuration

Create `docker-compose.prod.yml`:

```yaml
version: '3.8'

# Production-specific configuration
# Use: docker-compose -f docker-compose.yml -f docker-compose.prod.yml up

services:
  mongodb:
    # Use replica set in production
    command: mongod --replSet rs0 --bind_ip_all
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '1.0'
          memory: 1G

  redis:
    # Enable persistence in production
    command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD} --maxmemory 512mb --maxmemory-policy allkeys-lru
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

  rabbitmq:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

  stargate-server:
    # Use optimized image in production
    build:
      dockerfile: src/StarGate.Server/Dockerfile.optimized
    environment:
      ASPNETCORE_ENVIRONMENT: Production
      Logging__LogLevel__Default: Warning
      Logging__LogLevel__StarGate: Information
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '2.0'
          memory: 1G
        reservations:
          cpus: '1.0'
          memory: 512M
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s
```

### 4. Create Environment Template

Create `.env.template`:

```bash
# StarGate Environment Configuration
# Copy this file to .env and update values

# Build Information
VERSION=1.0.0
BUILD_DATE=2026-02-18T14:00:00Z
VCS_REF=abc1234

# Application Environment
ASPNETCORE_ENVIRONMENT=Development

# MongoDB
MONGO_PASSWORD=change-me-in-production

# Redis
REDIS_PASSWORD=change-me-in-production

# RabbitMQ
RABBITMQ_USER=stargate
RABBITMQ_PASSWORD=change-me-in-production

# StarGate Configuration
STARGATE_LOG_LEVEL=Information
```

### 5. Create MongoDB Initialization Script

Create `scripts/mongo-init.js`:

```javascript
// MongoDB initialization script
// Creates database, collections, and indexes

db = db.getSiblingDB('stargate');

print('Initializing StarGate database...');

// Create collections
db.createCollection('processes');
db.createCollection('processTypePolicies');
db.createCollection('clientPolicyOverrides');

print('Collections created');

// Create indexes for processes collection
db.processes.createIndex({ 'clientId': 1 });
db.processes.createIndex({ 'processType': 1 });
db.processes.createIndex({ 'clientProcessId': 1 });
db.processes.createIndex({ 'clientId': 1, 'clientProcessId': 1 }, { unique: true });
db.processes.createIndex({ 'status': 1 });
db.processes.createIndex({ 'createdAt': 1 });
db.processes.createIndex({ 'updatedAt': 1 });

print('Indexes created for processes');

// Create indexes for policies
db.processTypePolicies.createIndex({ 'processType': 1 }, { unique: true });
db.clientPolicyOverrides.createIndex(
  { 'clientId': 1, 'processType': 1 },
  { unique: true }
);

print('Indexes created for policies');

// Create application user (optional)
db.createUser({
  user: 'stargate-app',
  pwd: 'stargate-app-password',
  roles: [
    {
      role: 'readWrite',
      db: 'stargate'
    }
  ]
});

print('StarGate database initialization complete!');
```

### 6. Create RabbitMQ Configuration

Create `config/rabbitmq.conf`:

```ini
## RabbitMQ Configuration for StarGate

## Networking
listeners.tcp.default = 5672
management.tcp.port = 15672

## Memory
vm_memory_high_watermark.relative = 0.6
vm_memory_high_watermark_paging_ratio = 0.75

## Disk
disk_free_limit.relative = 1.0

## Clustering (for production)
cluster_formation.peer_discovery_backend = rabbit_peer_discovery_classic_config

## Logging
log.file.level = info
log.console = true
log.console.level = info

## Default vhost
default_vhost = stargate
default_user = guest
default_pass = guest

## Connection limits
connection_max = 1000
channel_max = 2000

## Queue settings
queue_master_locator = min-masters
```

### 7. Create Deployment Scripts

Create `scripts/deploy.sh`:

```bash
#!/bin/bash

# Deployment script for StarGate

set -e

ENV="${1:-dev}"

echo "============================================"
echo "Deploying StarGate - Environment: $ENV"
echo "============================================"

# Check if .env exists
if [ ! -f .env ]; then
    echo "Creating .env from template..."
    cp .env.template .env
    echo "⚠️  Please edit .env with your configuration"
    exit 1
fi

# Export build metadata
export BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ')
export VCS_REF=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
export VERSION=${VERSION:-$(git describe --tags --always 2>/dev/null || echo "dev")}

echo "Version: $VERSION"
echo "Build Date: $BUILD_DATE"
echo "VCS Ref: $VCS_REF"
echo ""

# Determine compose files
if [ "$ENV" = "prod" ]; then
    COMPOSE_FILES="-f docker-compose.yml -f docker-compose.prod.yml"
else
    COMPOSE_FILES="-f docker-compose.yml -f docker-compose.override.yml"
fi

echo "Using compose files: $COMPOSE_FILES"
echo ""

# Pull latest images for dependencies
echo "Pulling dependency images..."
docker-compose $COMPOSE_FILES pull mongodb redis rabbitmq

echo ""
echo "Building StarGate image..."
docker-compose $COMPOSE_FILES build stargate-server

echo ""
echo "Starting services..."
docker-compose $COMPOSE_FILES up -d

echo ""
echo "Waiting for services to be healthy..."
sleep 10

# Check service health
echo ""
echo "Checking service health..."
for i in {1..30}; do
    if curl -sf http://localhost:8080/health > /dev/null 2>&1; then
        echo "✓ StarGate is healthy!"
        break
    fi
    echo "Waiting for StarGate... ($i/30)"
    sleep 2
done

echo ""
echo "============================================"
echo "Deployment Complete!"
echo "============================================"
echo ""
echo "Services:"
echo "  API:              http://localhost:8080"
echo "  Health Check:     http://localhost:8080/health"
echo "  RabbitMQ UI:      http://localhost:15672"
if [ "$ENV" = "dev" ]; then
    echo "  Mongo Express:    http://localhost:8082"
fi
echo ""
echo "To view logs: docker-compose $COMPOSE_FILES logs -f"
echo "To stop: docker-compose $COMPOSE_FILES down"
echo "============================================"
```

Make executable:
```bash
chmod +x scripts/deploy.sh
```

Create `scripts/stop.sh`:

```bash
#!/bin/bash

# Stop StarGate services

ENV="${1:-dev}"

if [ "$ENV" = "prod" ]; then
    COMPOSE_FILES="-f docker-compose.yml -f docker-compose.prod.yml"
else
    COMPOSE_FILES="-f docker-compose.yml -f docker-compose.override.yml"
fi

echo "Stopping StarGate services..."
docker-compose $COMPOSE_FILES down

echo "Services stopped."
echo ""
echo "To remove volumes (WARNING: deletes all data):"
echo "  docker-compose $COMPOSE_FILES down -v"
```

Make executable:
```bash
chmod +x scripts/stop.sh
```

### 8. Create Health Check Script

Create `scripts/health-check.sh`:

```bash
#!/bin/bash

# Health check script for all services

echo "============================================"
echo "StarGate Health Check"
echo "============================================"
echo ""

# Check MongoDB
echo -n "MongoDB: "
if docker exec stargate-mongodb mongosh --quiet --eval "db.adminCommand('ping').ok" > /dev/null 2>&1; then
    echo "✓ Healthy"
else
    echo "❌ Unhealthy"
fi

# Check Redis
echo -n "Redis: "
if docker exec stargate-redis redis-cli ping > /dev/null 2>&1; then
    echo "✓ Healthy"
else
    echo "❌ Unhealthy"
fi

# Check RabbitMQ
echo -n "RabbitMQ: "
if docker exec stargate-rabbitmq rabbitmq-diagnostics ping > /dev/null 2>&1; then
    echo "✓ Healthy"
else
    echo "❌ Unhealthy"
fi

# Check StarGate Server
echo -n "StarGate Server: "
if curl -sf http://localhost:8080/health > /dev/null 2>&1; then
    echo "✓ Healthy"
    
    # Show detailed health
    echo ""
    echo "Detailed Health Status:"
    curl -s http://localhost:8080/health | jq .
else
    echo "❌ Unhealthy"
fi

echo ""
echo "Container Status:"
docker ps --filter "name=stargate-" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

echo ""
echo "============================================"
```

Make executable:
```bash
chmod +x scripts/health-check.sh
```

### 9. Create Comprehensive Documentation

Create `docs/DEPLOYMENT.md`:

```markdown
# Deployment Guide - StarGate

## Prerequisites

- Docker 20.10+
- Docker Compose 2.0+
- Git
- 4GB RAM minimum
- 10GB disk space

## Quick Start

### 1. Clone Repository
```bash
git clone https://github.com/artcava/StarGate.git
cd StarGate
```

### 2. Configure Environment
```bash
cp .env.template .env
# Edit .env with your configuration
```

### 3. Deploy
```bash
./scripts/deploy.sh
```

### 4. Verify
```bash
./scripts/health-check.sh
```

## Environment-Specific Deployment

### Development
```bash
./scripts/deploy.sh dev
```

Includes:
- Hot reload support
- Mongo Express UI
- Debug logging
- Development tools

### Production
```bash
./scripts/deploy.sh prod
```

Includes:
- Optimized images
- Resource limits
- Multiple replicas
- Production logging

## Manual Deployment

### Development
```bash
docker-compose up -d
```

### Production
```bash
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```

## Service URLs

| Service | URL | Credentials |
|---------|-----|-------------|
| API | http://localhost:8080 | - |
| Health Check | http://localhost:8080/health | - |
| RabbitMQ UI | http://localhost:15672 | guest/guest |
| Mongo Express (dev) | http://localhost:8082 | admin/admin |

## Configuration

### Environment Variables

See `.env.template` for all available variables.

**Required:**
- `MONGO_PASSWORD`
- `REDIS_PASSWORD`
- `RABBITMQ_PASSWORD`

**Optional:**
- `VERSION`
- `ASPNETCORE_ENVIRONMENT`
- `STARGATE_LOG_LEVEL`

### Volumes

**Persistent Data:**
- `stargate-mongodb-data` - MongoDB data
- `stargate-redis-data` - Redis data
- `stargate-rabbitmq-data` - RabbitMQ data
- `stargate-logs` - Application logs

**Backup:**
```bash
# Backup all volumes
docker run --rm \
  -v stargate-mongodb-data:/data \
  -v $(pwd)/backup:/backup \
  alpine tar czf /backup/mongodb-$(date +%Y%m%d).tar.gz /data
```

**Restore:**
```bash
# Restore from backup
docker run --rm \
  -v stargate-mongodb-data:/data \
  -v $(pwd)/backup:/backup \
  alpine tar xzf /backup/mongodb-20260218.tar.gz -C /
```

## Monitoring

### View Logs
```bash
# All services
docker-compose logs -f

# Specific service
docker-compose logs -f stargate-server

# Last 100 lines
docker-compose logs --tail 100 stargate-server
```

### Resource Usage
```bash
docker stats
```

### Health Checks
```bash
./scripts/health-check.sh
```

## Troubleshooting

### Services Won't Start

**Check logs:**
```bash
docker-compose logs
```

**Check dependencies:**
```bash
docker-compose ps
```

**Restart services:**
```bash
docker-compose restart
```

### Database Connection Issues

**Verify MongoDB:**
```bash
docker exec stargate-mongodb mongosh --eval "db.adminCommand('ping')"
```

**Check credentials:**
Verify `.env` file has correct passwords.

### Memory Issues

**Increase Docker memory:**
Docker Desktop → Settings → Resources → Memory → 4GB+

**Check resource usage:**
```bash
docker stats --no-stream
```

### Port Conflicts

**Find process using port:**
```bash
lsof -i :8080
```

**Change port in docker-compose.yml:**
```yaml
ports:
  - "8081:8080"  # Use 8081 instead
```

## Maintenance

### Update Images
```bash
docker-compose pull
docker-compose up -d
```

### Clean Up
```bash
# Stop and remove containers
docker-compose down

# Remove volumes (WARNING: deletes data)
docker-compose down -v

# Remove unused images
docker image prune -a
```

### Database Maintenance

**Backup:**
```bash
docker exec stargate-mongodb mongodump --out /backup
```

**Restore:**
```bash
docker exec stargate-mongodb mongorestore /backup
```

**Compact:**
```bash
docker exec stargate-mongodb mongosh --eval "db.runCommand({compact: 'processes'})"
```

## Security

### Production Checklist

- [ ] Change all default passwords
- [ ] Use secrets management (Docker secrets/Vault)
- [ ] Enable TLS for MongoDB
- [ ] Enable TLS for Redis
- [ ] Enable TLS for RabbitMQ
- [ ] Use strong passwords (>16 characters)
- [ ] Restrict network access
- [ ] Regular security updates
- [ ] Monitor for vulnerabilities

### Secrets Management

**Using Docker Secrets:**
```yaml
secrets:
  mongo_password:
    external: true

services:
  mongodb:
    secrets:
      - mongo_password
    environment:
      MONGO_PASSWORD_FILE: /run/secrets/mongo_password
```

## Scaling

### Horizontal Scaling

**Scale API servers:**
```bash
docker-compose up -d --scale stargate-server=3
```

**Add load balancer:**
Add nginx or Traefik in front of API servers.

### Vertical Scaling

**Increase resources:**
```yaml
services:
  stargate-server:
    deploy:
      resources:
        limits:
          cpus: '4.0'
          memory: 2G
```

## Migration to Kubernetes

For production deployment, consider migrating to Kubernetes:

1. Convert compose to Kubernetes manifests
2. Use Helm charts
3. Implement proper secrets management
4. Setup monitoring (Prometheus/Grafana)
5. Configure autoscaling

See `docs/KUBERNETES.md` (Phase 11) for details.
```

## ✅ Acceptance Criteria

- [ ] docker-compose.yml completed with all services
- [ ] docker-compose.override.yml for development
- [ ] docker-compose.prod.yml for production
- [ ] .env.template created
- [ ] MongoDB initialization script created
- [ ] RabbitMQ configuration created
- [ ] Deployment scripts created
- [ ] Health check script created
- [ ] All services start successfully
- [ ] Service dependencies configured correctly
- [ ] Health checks pass for all services
- [ ] Volumes configured for persistence
- [ ] Networking configured correctly
- [ ] Services can communicate
- [ ] Documentation complete
- [ ] Code follows CODING-CONVENTIONS.md

## 📝 Testing Instructions

```bash
# Test development deployment
./scripts/deploy.sh dev

# Verify all services
./scripts/health-check.sh

# Test API
curl http://localhost:8080/health

# Test process creation
curl -X POST http://localhost:8080/api/processes \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "test-client",
    "processType": "order",
    "clientProcessId": "test-123",
    "metadata": {"orderId": "order-456"}
  }'

# Check RabbitMQ UI
open http://localhost:15672

# Check Mongo Express (dev only)
open http://localhost:8082

# View logs
docker-compose logs -f stargate-server

# Test production deployment
./scripts/deploy.sh prod

# Check resource usage
docker stats

# Test restart
docker-compose restart stargate-server
./scripts/health-check.sh

# Test scaling
docker-compose up -d --scale stargate-server=2

# Cleanup
./scripts/stop.sh
```

## 📚 References

- [TECHNICAL-ANALYSIS.md - Phase 10.2](https://github.com/artcava/StarGate/blob/develop/docs/TECHNICAL-ANALYSIS.md)
- [Docker Compose Documentation](https://docs.docker.com/compose/)
- [Docker Compose File Reference](https://docs.docker.com/compose/compose-file/)
- [Docker Networking](https://docs.docker.com/network/)
- [CODING-CONVENTIONS.md](https://github.com/artcava/StarGate/blob/main/docs/CODING-CONVENTIONS.md)

## 🏷️ Labels

`phase-10` `containerization` `sprint-10.2` `docker-compose` `orchestration` `deployment`

## ⏱️ Estimated Effort

**10-14 hours**

## 🔗 Dependencies

- Issue #113: Dockerfiles must be created first
- All infrastructure components implemented

## 🔗 Related Issues

Part of Phase 10: Containerization - Sprint 10.2: Orchestration

## 📌 Important Notes

### Docker Compose Benefits

**Single Command Deployment:**
- All services start together
- Proper dependency order
- Network configuration automatic
- Volume management simplified

**Environment Isolation:**
- Development and production configs
- Easy switching between environments
- Reproducible deployments

### Service Dependencies

**Dependency Chain:**
```
StarGate Server
  ↓ depends_on (healthy)
MongoDB + Redis + RabbitMQ
```

**Health Check Integration:**
- Services wait for dependencies
- Only start when dependencies healthy
- Automatic retry on failure

### Volume Strategy

**Named Volumes:**
- Persistent across container restarts
- Easy backup/restore
- Clear naming
- Managed by Docker

**Bind Mounts (Dev):**
- Configuration files
- Source code (hot reload)
- Logs for easy access

### Network Configuration

**Bridge Network:**
- Services can communicate by name
- Isolated from host network
- DNS resolution automatic

**Service Discovery:**
```
mongodb://mongodb:27017  # Not localhost!
redis://redis:6379
rabbitmq://rabbitmq:5672
```

### Environment-Specific Configuration

**Development:**
- Debug logging
- Development tools (Mongo Express)
- No resource limits
- Hot reload support
- Single replica

**Production:**
- Info/Warning logging
- Optimized images
- Resource limits
- Multiple replicas
- Health checks strict

### Restart Policies

**`unless-stopped`:**
- Restart on failure
- Don't restart if manually stopped
- Good for most services

**`on-failure`:**
- Only restart on error
- Used with retry limits
- Good for production

**`no`:**
- Never restart
- Good for development

### Health Check Configuration

**Parameters:**
- `interval`: How often to check
- `timeout`: Max time for check
- `retries`: Failures before unhealthy
- `start_period`: Grace period on startup

**Example:**
```yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 40s
```

### Resource Limits

**Why:**
- Prevent resource exhaustion
- Fair resource distribution
- Predictable performance

**Configuration:**
```yaml
deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 1G
    reservations:
      cpus: '1.0'
      memory: 512M
```

### Logging Strategy

**JSON File Driver:**
- Logs to file
- Automatic rotation
- Queryable with `docker logs`

**Configuration:**
```yaml
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"
```

**Max 30MB per service** (10MB × 3 files)

### MongoDB Initialization

**mongo-init.js:**
- Runs once on first startup
- Creates database and collections
- Creates indexes
- Creates application user

**Index Strategy:**
- Query performance
- Unique constraints
- Compound indexes

### RabbitMQ Configuration

**Key Settings:**
- Memory watermark (60%)
- Disk free limit
- Connection limits
- Queue settings

**Management UI:**
- Monitor queues
- Check connections
- View message rates
- Debug issues

### Common Issues

**Port Conflicts:**
- Another service using port
- Change port mapping
- Stop conflicting service

**Permission Errors:**
- Volume mount permissions
- Use named volumes
- Check user in container

**OOM Kills:**
- Increase Docker memory
- Add resource limits
- Optimize application

**Slow Startup:**
- Dependencies not healthy
- Increase start_period
- Check logs

### Best Practices

1. **Use .env for secrets** (don't commit .env)
2. **Named volumes for data** (easier management)
3. **Health checks for all services** (proper orchestration)
4. **Resource limits** (prevent exhaustion)
5. **Log rotation** (prevent disk full)
6. **Backup volumes regularly** (data safety)
7. **Update images regularly** (security)
8. **Monitor resource usage** (capacity planning)

### Deployment Workflow

```
1. Configure .env
   ↓
2. Run deploy script
   ↓
3. Wait for health checks
   ↓
4. Verify API endpoints
   ↓
5. Monitor logs
   ↓
6. Ready for traffic
```

### Scaling Considerations

**Horizontal:**
- Multiple API instances
- Load balancer needed
- Session persistence required

**Vertical:**
- Increase CPU/memory
- Better for databases
- Limited by host resources

**Database:**
- MongoDB replica set
- Redis sentinel/cluster
- RabbitMQ cluster

Service	URL	Credentials
API	http://localhost:8080	-
Health Check	http://localhost:8080/health	-
RabbitMQ UI	http://localhost:15672	guest/guest
Mongo Express (dev)	http://localhost:8082	admin/admin

Phase 10.2: Complete Docker Compose Configuration and Deployment Documentation #114

Description

📋 Task Description

🎯 Objectives

📦 Deliverables

1. Create Main Docker Compose File

2. Create Development Override

3. Create Production Configuration

4. Create Environment Template

5. Create MongoDB Initialization Script

6. Create RabbitMQ Configuration

7. Create Deployment Scripts

8. Create Health Check Script

9. Create Comprehensive Documentation

2. Configure Environment

3. Deploy

4. Verify

Environment-Specific Deployment

Development

Production

Manual Deployment

Development

Production

Service URLs

Configuration

Environment Variables

Volumes

Monitoring

View Logs

Resource Usage

Health Checks

Troubleshooting

Services Won't Start

Database Connection Issues

Memory Issues

Port Conflicts

Maintenance

Update Images

Clean Up

Database Maintenance

Security

Production Checklist

Secrets Management

Scaling

Horizontal Scaling

Vertical Scaling

Migration to Kubernetes

📚 References

🏷️ Labels

⏱️ Estimated Effort

🔗 Dependencies

🔗 Related Issues

📌 Important Notes

Docker Compose Benefits

Service Dependencies

Volume Strategy

Network Configuration

Environment-Specific Configuration

Restart Policies

Health Check Configuration

Resource Limits

Logging Strategy

MongoDB Initialization

RabbitMQ Configuration

Common Issues

Best Practices

Deployment Workflow

Scaling Considerations

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions