SerpentRace/SerpentRace_Docker/deployment/README.md

# SerpentRace Production Deployment Guide

## Overview
This package contains everything needed to deploy SerpentRace in a production environment using pre-built Docker images.

## Package Contents
- `serpentRaceDocker.tar` - All Docker images packed for deployment
- `docker-compose.deploy.yml` - Production Docker Compose configuration
- `.env.server` - Environment variables template for production
- `load-images.bat` - Automated deployment script for Windows servers
- `README.md` - This deployment guide

## System Requirements
- Windows Server 2016+ or Windows 10/11
- Docker Desktop or Docker Engine
- Docker Compose
- Minimum 4GB RAM, 20GB free disk space
- Network ports: 80, 443, 3000, 5432, 6379, 9000, 9001

## Pre-Deployment Configuration

### 1. Environment Variables
Edit `.env.server` and update the following **REQUIRED** settings:

```bash
# Database - Use a strong password
POSTGRES_PASSWORD=your_strong_database_password

# JWT Security - Use a random 32+ character string
JWT_SECRET=your_super_secret_jwt_key_32_chars_minimum

# Redis Security
REDIS_PASSWORD=your_redis_password

# MinIO Storage
MINIO_ACCESS_KEY=your_minio_admin_user
MINIO_SECRET_KEY=your_minio_secret_key

# Email Configuration (for notifications)
EMAIL_HOST=smtp.yourmailprovider.com
EMAIL_USER=your_email@yourdomain.com
EMAIL_PASS=your_email_password
EMAIL_FROM="SerpentRace <noreply@yourdomain.com>"

# Application URL
APP_BASE_URL=http://your-domain.com
```

### 2. Security Checklist
- [ ] Changed all default passwords
- [ ] Generated strong JWT secret (32+ characters)
- [ ] Configured email settings
- [ ] Updated domain name in APP_BASE_URL
- [ ] Configured firewall rules
- [ ] Planned SSL certificate setup

## Deployment Steps

### Automatic Deployment (Recommended)
1. Extract all files to your server directory
2. Edit `.env.server` with your configuration
3. Run `load-images.bat`
4. Follow the prompts

### Manual Deployment
1. Load Docker images:
   ```cmd
   docker load -i serpentRaceDocker.tar
   ```

2. Start services:
   ```cmd
   docker-compose -f docker-compose.deploy.yml --env-file .env.server up -d
   ```

## Post-Deployment

### Verify Services
Check that all services are running:
```cmd
docker-compose -f docker-compose.deploy.yml ps
```

### Access Points
- **Frontend Application**: http://localhost (or your domain)
- **Backend API**: http://localhost:3000
- **MinIO Console**: http://localhost:9001
- **Database**: localhost:5432 (internal access only)

### Initial Setup
1. Access the frontend and verify it loads
2. Test user registration and login
3. Check backend API health: http://localhost:3000/health
4. Access MinIO console to verify storage

### Security Hardening

#### Firewall Configuration
Open only necessary ports:
- Port 80 (HTTP) - Public
- Port 443 (HTTPS) - Public (when SSL configured)
- Ports 3000, 5432, 6379, 9000, 9001 - Internal/VPN only

#### SSL/TLS Setup
1. Obtain SSL certificates (Let's Encrypt, commercial CA)
2. Configure nginx for HTTPS in the frontend container
3. Update APP_BASE_URL to use https://

#### Regular Maintenance
- Monitor logs: `docker-compose -f docker-compose.deploy.yml logs -f`
- Update images periodically
- Backup database and MinIO data
- Monitor disk space and performance

## Management Commands

### View Logs
```cmd
# All services
docker-compose -f docker-compose.deploy.yml logs -f

# Specific service
docker-compose -f docker-compose.deploy.yml logs -f backend
```

### Restart Services
```cmd
# Restart all
docker-compose -f docker-compose.deploy.yml restart

# Restart specific service
docker-compose -f docker-compose.deploy.yml restart backend
```

### Stop Services
```cmd
docker-compose -f docker-compose.deploy.yml down
```

### Update Deployment
1. Stop current services
2. Load new images
3. Start services with new configuration

## Backup Strategy

### Database Backup
```cmd
docker exec serpentrace-postgres pg_dump -U postgres serpentrace > backup_$(date +%Y%m%d).sql
```

### Complete Backup
```cmd
# Stop services
docker-compose -f docker-compose.deploy.yml down

# Backup volumes
docker run --rm -v postgres_data:/data -v %cd%:/backup ubuntu tar czf /backup/postgres_backup.tar.gz -C /data .
docker run --rm -v minio_data:/data -v %cd%:/backup ubuntu tar czf /backup/minio_backup.tar.gz -C /data .

# Restart services
docker-compose -f docker-compose.deploy.yml up -d
```

## Troubleshooting

### Common Issues

#### Services Not Starting
1. Check Docker is running
2. Verify port availability
3. Check environment variables
4. Review logs for specific errors

#### Database Connection Issues
1. Verify POSTGRES_PASSWORD matches in .env.server
2. Check database container is healthy
3. Ensure network connectivity

#### Frontend Not Loading
1. Check nginx container status
2. Verify backend API is responding
3. Check browser console for errors

#### Performance Issues
1. Monitor resource usage: `docker stats`
2. Check available disk space
3. Review application logs
4. Consider scaling if needed

### Getting Help
- Check application logs for specific error messages
- Verify all environment variables are set correctly
- Ensure all required ports are available
- Contact support with log files and configuration details

## Version Information
- SerpentRace Backend: Latest
- Frontend: Latest  
- PostgreSQL: 15-alpine
- Redis: 7-alpine
- MinIO: Latest
- Nginx: Alpine