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:

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

   docker load -i serpentRaceDocker.tar
   

2. Start services:

   docker-compose -f docker-compose.deploy.yml --env-file .env.server up -d
   

Post-Deployment

Verify Services

Check that all services are running:

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

# 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

# Restart all
docker-compose -f docker-compose.deploy.yml restart

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

Stop Services

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

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

Complete Backup

# 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