Project Init
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Yaojia Wang
432
DOCKER-README.md
Normal file
432
DOCKER-README.md
Normal file
@@ -0,0 +1,432 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user