Backend Complete: Interface Refactoring & Service Container Enhancements
Repository Interface Optimization: - Created IBaseRepository.ts and IPaginatedRepository.ts - Refactored all 7 repository interfaces to extend base interfaces - Eliminated ~200 lines of redundant code (70% reduction) - Improved type safety and maintainability Dependency Injection Improvements: - Added EmailService and GameTokenService to DIContainer - Updated CreateUserCommandHandler constructor for DI - Updated RequestPasswordResetCommandHandler constructor for DI - Enhanced testability and service consistency Environment Configuration: - Created comprehensive .env.example with 40+ variables - Organized into 12 logical sections (Database, Security, Email, etc.) - Added security guidelines and best practices - Documented all backend environment requirements Documentation: - Added comprehensive codebase review - Created refactoring summary report - Added frontend implementation guide Impact: Improved code quality, reduced maintenance overhead, enhanced developer experience
This commit is contained in:
@@ -0,0 +1,267 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user