SerpentRace/SerpentRace_Docker/DOCKER_README.md

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:

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

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

   # 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

# 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

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

POSTGRES_PASSWORD=postgres
JWT_SECRET=dev_jwt_secret_change_in_production
MINIO_ACCESS_KEY=serpentrace
MINIO_SECRET_KEY=serpentrace123!

Production (.env.prod)

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

# 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

# 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