268 lines
7.3 KiB
Markdown
268 lines
7.3 KiB
Markdown
# 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
|