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

# 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

# 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:

# 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

# 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

# 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

# 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

# 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.

# 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:

# 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:

# 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:

# 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:

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

Build Cache

Speed up rebuilds by leveraging Docker build cache:

# 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:

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

# 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:

# Copy template
cp .env.example .env

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

Multi-Environment Setup

# 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:

# 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
• Frontend Development Guide
• Testing Guide
• Architecture Documentation

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