ColaFlow/DOCKER-README.md

# ColaFlow Docker Development Environment

This document explains how to set up and use the Docker-based development environment for ColaFlow.

## Prerequisites

- **Docker Desktop** (latest version)
  - Windows: Docker Desktop for Windows with WSL2
  - Mac: Docker Desktop for Mac
  - Linux: Docker Engine + Docker Compose
- **Git** (for cloning repository)
- **Minimum System Requirements**:
  - 8GB RAM (16GB recommended)
  - 20GB free disk space
  - 4 CPU cores

## Quick Start

### 1. Start All Services

```bash
# Start all core services (PostgreSQL, Redis, Backend, Frontend)
docker-compose up -d

# View logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f backend
docker-compose logs -f frontend
```

### 2. Access Services

| Service | URL | Credentials |
|---------|-----|-------------|
| **Frontend** | http://localhost:3000 | N/A |
| **Backend API** | http://localhost:5000 | N/A |
| **API Documentation** | http://localhost:5000/scalar/v1 | N/A |
| **PostgreSQL** | localhost:5432 | User: `colaflow` / Password: `colaflow_dev_password` |
| **Redis** | localhost:6379 | Password: `colaflow_redis_password` |
| **pgAdmin** (optional) | http://localhost:5050 | Email: `admin@colaflow.com` / Password: `admin` |
| **Redis Commander** (optional) | http://localhost:8081 | N/A |

### 3. Stop Services

```bash
# Stop all services (preserves data)
docker-compose stop

# Stop and remove containers (preserves volumes)
docker-compose down

# Stop and remove everything including volumes (⚠️ DATA LOSS)
docker-compose down -v
```

## Service Details

### Core Services

#### PostgreSQL (Database)
- **Image**: `postgres:16-alpine`
- **Port**: 5432
- **Database**: `colaflow`
- **Volume**: `postgres_data` (persistent)
- **Health Check**: Automatic readiness check

#### Redis (Cache & Session Store)
- **Image**: `redis:7-alpine`
- **Port**: 6379
- **Persistence**: AOF (Append-Only File)
- **Volume**: `redis_data` (persistent)

#### Backend API (.NET 9)
- **Port**: 5000 (HTTP)
- **Dependencies**: PostgreSQL + Redis
- **Hot Reload**: Enabled (when volume mounted)
- **Health Endpoint**: http://localhost:5000/health

#### Frontend (Next.js 15)
- **Port**: 3000
- **Dependencies**: Backend API
- **Hot Reload**: Enabled (via volume mounts)
- **Dev Mode**: Enabled by default

### Test Services

#### PostgreSQL Test Database
- **Port**: 5433
- **Database**: `colaflow_test`
- **Purpose**: Integration testing (Testcontainers)
- **Storage**: In-memory (tmpfs)

### Optional Tools

To enable optional management tools:

```bash
# Start with tools (pgAdmin + Redis Commander)
docker-compose --profile tools up -d

# Or set in .env file
COMPOSE_PROFILES=tools
```

#### pgAdmin (Database Management)
- Visual PostgreSQL management
- Access: http://localhost:5050
- Add server manually:
  - Host: `postgres`
  - Port: `5432`
  - Database: `colaflow`
  - Username: `colaflow`
  - Password: `colaflow_dev_password`

#### Redis Commander (Redis Management)
- Visual Redis key-value browser
- Access: http://localhost:8081

## Development Workflows

### Building from Source

The Docker Compose setup expects the following directory structure:

```
product-master/
├── docker-compose.yml
├── src/                          # Backend source code
│   ├── ColaFlow.API/
│   ├── ColaFlow.Application/
│   ├── ColaFlow.Domain/
│   ├── ColaFlow.Infrastructure/
│   └── Dockerfile.backend        # Backend Dockerfile
├── colaflow-web/                 # Frontend source code
│   ├── app/
│   ├── components/
│   ├── lib/
│   └── Dockerfile                # Frontend Dockerfile
└── scripts/
    └── init-db.sql
```

### Backend Development

```bash
# Rebuild backend after code changes
docker-compose up -d --build backend

# View backend logs
docker-compose logs -f backend

# Execute commands in backend container
docker-compose exec backend dotnet --version
docker-compose exec backend dotnet ef migrations list
```

### Frontend Development

```bash
# Rebuild frontend after dependency changes
docker-compose up -d --build frontend

# View frontend logs
docker-compose logs -f frontend

# Install new npm packages
docker-compose exec frontend npm install <package-name>
```

### Database Operations

```bash
# Access PostgreSQL CLI
docker-compose exec postgres psql -U colaflow -d colaflow

# Backup database
docker-compose exec postgres pg_dump -U colaflow colaflow > backup.sql

# Restore database
docker-compose exec -T postgres psql -U colaflow -d colaflow < backup.sql

# View database logs
docker-compose logs -f postgres
```

### Redis Operations

```bash
# Access Redis CLI
docker-compose exec redis redis-cli -a colaflow_redis_password

# View Redis logs
docker-compose logs -f redis

# Clear all Redis data
docker-compose exec redis redis-cli -a colaflow_redis_password FLUSHALL
```

## Testing

### Integration Tests

The `postgres-test` service provides an isolated test database for integration tests.

```bash
# Start test database
docker-compose up -d postgres-test

# Run integration tests (from host)
cd src/ColaFlow.API.Tests
dotnet test --filter Category=Integration

# Test database connection string
Host=localhost;Port=5433;Database=colaflow_test;Username=colaflow_test;Password=colaflow_test_password
```

### Testcontainers

For automated integration testing, Testcontainers will spin up temporary Docker containers automatically. No manual setup required.

## Troubleshooting

### Docker Desktop Not Running

**Error**: `error during connect: Get "http:///.../docker...": open //./pipe/docker...`

**Solution**:
1. Start Docker Desktop
2. Wait for it to fully initialize (green icon in system tray)
3. Retry your command

### Port Already in Use

**Error**: `Bind for 0.0.0.0:5432 failed: port is already allocated`

**Solution**:
```bash
# Find process using the port (Windows)
netstat -ano | findstr :5432

# Kill the process
taskkill /PID <PID> /F

# Or change port in docker-compose.yml
ports:
  - "5433:5432"  # Map to different host port
```

### Container Health Check Failing

**Error**: `container "colaflow-postgres" is unhealthy`

**Solution**:
```bash
# Check container logs
docker-compose logs postgres

# Restart the service
docker-compose restart postgres

# Remove and recreate
docker-compose down
docker-compose up -d
```

### Out of Disk Space

**Error**: `no space left on device`

**Solution**:
```bash
# Remove unused images and containers
docker system prune -a

# Remove unused volumes (⚠️ deletes data)
docker volume prune
```

### Backend Cannot Connect to Database

**Symptoms**: Backend crashes on startup or shows connection errors

**Solution**:
1. Check PostgreSQL is healthy: `docker-compose ps`
2. Verify connection string in `docker-compose.yml`
3. Check logs: `docker-compose logs postgres`
4. Ensure health checks pass before backend starts (depends_on conditions)

### Frontend Cannot Connect to Backend

**Symptoms**: API calls fail with CORS or connection errors

**Solution**:
1. Check backend is running: `curl http://localhost:5000/health`
2. Verify `NEXT_PUBLIC_API_URL` in frontend environment
3. Check CORS settings in backend configuration
4. Review logs: `docker-compose logs backend frontend`

## Performance Optimization

### Memory Limits

Add memory limits to prevent Docker from consuming too much RAM:

```yaml
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 1G
        reservations:
          memory: 512M
```

### Build Cache

Speed up rebuilds by leveraging Docker build cache:

```bash
# Use BuildKit for better caching
DOCKER_BUILDKIT=1 docker-compose build

# Set as default (add to .bashrc or .zshrc)
export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1
```

### Volume Performance

For better I/O performance on Windows/Mac:

```yaml
volumes:
  - ./colaflow-web:/app:cached  # Better read performance
```

## Security Notes

### Development Credentials

⚠️ **NEVER use these credentials in production!**

All passwords and secrets in `docker-compose.yml` are for **local development only**.

### Production Deployment

For production:
1. Use environment-specific compose files
2. Store secrets in secure vaults (Azure Key Vault, AWS Secrets Manager, etc.)
3. Enable HTTPS/TLS
4. Use strong passwords
5. Implement network segmentation
6. Enable authentication on all services

## Advanced Usage

### Running Individual Services

```bash
# Start only database
docker-compose up -d postgres redis

# Start backend without frontend
docker-compose up -d postgres redis backend
```

### Custom Configuration

Create a `.env` file for custom settings:

```bash
# Copy template
cp .env.example .env

# Edit .env with your values
# Then start services
docker-compose up -d
```

### Multi-Environment Setup

```bash
# Development (default)
docker-compose up -d

# Staging
docker-compose -f docker-compose.yml -f docker-compose.staging.yml up -d

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

## Clean Slate Restart

To completely reset your environment:

```bash
# Stop all containers
docker-compose down -v

# Remove all ColaFlow images
docker images | grep colaflow | awk '{print $3}' | xargs docker rmi -f

# Remove all unused Docker resources
docker system prune -a --volumes

# Restart from scratch
docker-compose up -d --build
```

## Next Steps

- [Backend Development Guide](./docs/backend-guide.md)
- [Frontend Development Guide](./docs/frontend-guide.md)
- [Testing Guide](./tests/README.md)
- [Architecture Documentation](./docs/M1-Architecture-Design.md)

## Support

For issues with Docker setup:
1. Check this README's Troubleshooting section
2. Review Docker Compose logs: `docker-compose logs`
3. Check Docker Desktop is up-to-date
4. Consult team documentation

---

**Last Updated**: 2025-11-02
**Maintained By**: QA Team