# SerpentRace Docker Development Environment

This Docker setup provides a complete development environment for SerpentRace with hot reloading and all necessary services.

## 🚀 Quick Start

### Development Environment

1. **Start the development environment:**
   ```bash
   # Windows
   docker-manage.bat dev:start
   
   # Linux/Mac
   ./docker-manage.sh dev:start
   ```

2. **Access the applications:**
   - **Frontend:** http://localhost:5173
   - **Backend API:** http://localhost:3000
   - **Swagger API Docs:** http://localhost:3000/api-docs
   - **PostgreSQL:** localhost:5432 (user: postgres, password: postgres)
   - **Redis:** localhost:6379
   - **MinIO Console:** http://localhost:9001 (serpentrace / serpentrace123!)
   - **PgAdmin:** http://localhost:8080 (admin@serpentrace.dev / admin)
   - **Redis Commander:** http://localhost:8081

3. **Stop the environment:**
   ```bash
   # Windows
   docker-manage.bat dev:stop
   
   # Linux/Mac
   ./docker-manage.sh dev:stop
   ```

### Production Environment

1. **Configure production environment:**
   - Copy `.env.prod` and update all values with secure passwords
   - Update JWT secrets and database passwords

2. **Start production:**
   ```bash
   # Windows
   docker-manage.bat prod:start
   
   # Linux/Mac
   ./docker-manage.sh prod:start
   ```

## 📁 File Structure

```
SzeSnake/
├── docker-compose.dev.yml          # Development environment
├── docker-compose.prod.yml         # Production environment
├── docker-manage.sh                # Linux/Mac management script
├── docker-manage.bat               # Windows management script
├── .env.dev                        # Development environment variables
├── .env.prod                       # Production environment variables
├── SerpentRace_Backend/
│   ├── Dockerfile                  # Production backend image
│   ├── Dockerfile.dev              # Development backend image
│   └── .dockerignore
└── SerpentRace_Frontend/
    ├── Dockerfile                  # Production frontend image
    ├── Dockerfile.dev              # Development frontend image
    ├── nginx.conf                  # Nginx configuration for production
    └── .dockerignore
```

## 🛠 Development Features

### Hot Reloading
- **Backend:** Uses `nodemon` and `ts-node` for automatic TypeScript compilation and server restart
- **Frontend:** Uses Vite's built-in HMR (Hot Module Replacement)

### Volume Mapping
- Source code is mounted as volumes for instant file changes
- Node modules are preserved in named volumes for performance

### Development Tools
- **PgAdmin:** Web-based PostgreSQL administration
- **Redis Commander:** Web-based Redis management
- **MinIO Console:** Object storage management

### Database Initialization
- Automatic database setup with test data from `sql_dump_with_test_data.sql`

## 🐳 Docker Services

### Backend (`backend`)
- **Image:** Node.js 20 Alpine
- **Port:** 3000
- **Features:** Hot reload, TypeScript support
- **Dependencies:** PostgreSQL, Redis, MinIO

### Frontend (`frontend`)
- **Image:** Node.js 20 Alpine (dev) / Nginx Alpine (prod)
- **Port:** 5173 (dev) / 80 (prod)
- **Features:** Vite HMR, React Fast Refresh

### PostgreSQL (`postgres`)
- **Image:** PostgreSQL 15 Alpine
- **Port:** 5432
- **Database:** serpentrace
- **Credentials:** postgres/postgres (dev)

### Redis (`redis`)
- **Image:** Redis 7 Alpine
- **Port:** 6379
- **Features:** Persistence enabled

### MinIO (`minio`)
- **Image:** MinIO latest
- **Ports:** 9000 (API), 9001 (Console)
- **Features:** S3-compatible object storage

## 🔧 Management Commands

### Using the Management Scripts

```bash
# Start development environment
./docker-manage.sh dev:start

# Stop development environment
./docker-manage.sh dev:stop

# View logs for all services
./docker-manage.sh logs

# View logs for specific service
./docker-manage.sh logs backend
./docker-manage.sh logs frontend

# Clean up all resources
./docker-manage.sh cleanup

# Production commands
./docker-manage.sh prod:start
./docker-manage.sh prod:stop
```

### Manual Docker Compose Commands

```bash
# Development
docker-compose -f docker-compose.dev.yml --env-file .env.dev up --build -d
docker-compose -f docker-compose.dev.yml down

# Production
docker-compose -f docker-compose.prod.yml --env-file .env.prod up --build -d
docker-compose -f docker-compose.prod.yml down

# View logs
docker-compose -f docker-compose.dev.yml logs -f [service_name]

# Rebuild specific service
docker-compose -f docker-compose.dev.yml up --build backend

# Execute commands in running containers
docker-compose -f docker-compose.dev.yml exec backend npm run test
docker-compose -f docker-compose.dev.yml exec postgres psql -U postgres -d serpentrace
```

## 🔒 Security Considerations

### Development
- Default passwords are used for convenience
- Services are exposed on localhost
- Debug tools are included

### Production
- **IMPORTANT:** Update all passwords in `.env.prod`
- Use strong JWT secrets (256+ characters recommended)
- Services are not directly exposed
- No debug tools included

## 🐛 Troubleshooting

### Common Issues

1. **Port conflicts:**
   - Check if ports 3000, 5173, 5432, 6379, 9000, 9001, 8080, 8081 are available
   - Modify port mappings in docker-compose files if needed

2. **File watching issues on Windows:**
   - WSL2 is recommended for better file system performance
   - Ensure Docker Desktop is configured to use WSL2

3. **Database connection issues:**
   - Wait for health checks to pass before the application starts
   - Check logs: `./docker-manage.sh logs postgres`

4. **Hot reload not working:**
   - Ensure volumes are properly mounted
   - Check file permissions on Linux/Mac systems

### Performance Tips

1. **Use WSL2 on Windows** for better file system performance
2. **Increase Docker memory** allocation if needed
3. **Use .dockerignore** to exclude unnecessary files
4. **Prune unused Docker resources** regularly: `docker system prune`

## 📝 Environment Variables

### Development (.env.dev)
```bash
POSTGRES_PASSWORD=postgres
JWT_SECRET=dev_jwt_secret_change_in_production
MINIO_ACCESS_KEY=serpentrace
MINIO_SECRET_KEY=serpentrace123!
```

### Production (.env.prod)
```bash
POSTGRES_PASSWORD=your_secure_password
JWT_SECRET=your_very_long_secure_jwt_secret
MINIO_ACCESS_KEY=your_minio_access_key
MINIO_SECRET_KEY=your_secure_minio_secret
```

## 🔄 Health Checks

All services include health checks to ensure proper startup order:
- **PostgreSQL:** `pg_isready`
- **Redis:** `redis-cli ping`
- **MinIO:** HTTP health endpoint
- **Backend:** HTTP health endpoint
- **Frontend:** HTTP health endpoint (production)

The application will only start after all dependencies are healthy.

## 📊 Monitoring

### Logs
```bash
# All services
./docker-manage.sh logs

# Specific service
./docker-manage.sh logs backend
./docker-manage.sh logs frontend
./docker-manage.sh logs postgres
```

### Service Status
```bash
# Check running containers
docker ps

# Check service health
docker-compose -f docker-compose.dev.yml ps
```

## 🚀 Deployment

For production deployment:

1. Update `.env.prod` with secure values
2. Ensure proper firewall configuration
3. Use reverse proxy (nginx/traefik) for SSL termination
4. Consider using Docker Swarm or Kubernetes for orchestration
5. Set up monitoring and backup solutions