Fix deployment issue, see DEPLOYMENT_MIGRATION_GUIDE_en.md

DEPLOYMENT_MIGRATION_GUIDE_en.md

@@ -0,0 +1,321 @@
+# Deployment Migration Guide for Production Environment
+
+## Recommended Procedure (Safe Approach)
+
+### Pattern A: Fresh Clean Deployment (Recommended)
+
+```bash
+# 1. Create backup of old database
+pg_dump rogaining_db > backup_$(date +%Y%m%d_%H%M%S).sql
+
+# 2. Get latest code with Git pull
+git pull origin main
+
+# 3. Perform batch reset with migration_simple_reset.py (Recommended)
+docker compose exec app python migration_simple_reset.py --full
+
+# 4. Execute data restoration scripts if needed
+# (When existing data is present)
+```
+
+### Pattern B: Gradual Migration Fix
+
+```bash
+# 1. Create backup of old database
+pg_dump rogaining_db > backup_$(date +%Y%m%d_%H%M%S).sql
+
+# 2. Get latest code with Git pull
+git pull origin main
+
+# 3. Temporarily remove problematic migration file
+rm rog/migrations/0011_auto_20250827_1459.py
+
+# 4. Apply migrations up to the last working one
+docker compose exec app python manage.py migrate
+
+# 5. Clean up with migration_simple_reset.py
+docker compose exec app python migration_simple_reset.py --reset-only
+docker compose exec app python migration_simple_reset.py --apply-only
+```
+
+## ⚠️ Issues with Original Proposed Procedure
+
+```bash
+1) Restore old DB ✅ OK
+2) Git pull to deploy latest code ✅ OK  
+3) Run migrate to update DB ❌ Problem: Will fail with dependency error
+4) Execute migration_simple_reset.py ✅ OK
+```
+
+**Issue**: Step 3 will encounter `NodeNotFoundError` and migration will fail.
+
+## Specific Deployment Procedure (Production Recommended)
+
+### Pre-deployment Preparation
+```bash
+# Verify connection to production environment
+docker compose ps
+
+# Check current migration status
+docker compose exec app python manage.py showmigrations
+```
+
+### Execution Steps
+
+#### Step 1: Create Backups
+```bash
+# Database backup
+docker compose exec postgres-db pg_dump -U admin rogaining_db > deploy_backup_$(date +%Y%m%d_%H%M%S).sql
+
+# Current migration files backup
+cp -r rog/migrations rog/migrations_backup_deploy_$(date +%Y%m%d_%H%M%S)
+```
+
+#### Step 2: Code Update
+```bash
+# Get latest code
+git pull origin main
+
+# Verify migration_simple_reset.py exists
+ls -la migration_simple_reset.py
+```
+
+#### Step 3: Execute Migration Reset
+```bash
+# Complete reset (recommended)
+docker compose exec app python migration_simple_reset.py --full
+```
+
+Or step-by-step execution:
+```bash
+# Backup only
+docker compose exec app python migration_simple_reset.py --backup-only
+
+# Reset only
+docker compose exec app python migration_simple_reset.py --reset-only
+
+# Apply only
+docker compose exec app python migration_simple_reset.py --apply-only
+```
+
+#### Step 4: Verify Results
+```bash
+# Check migration status
+docker compose exec app python manage.py showmigrations
+
+# Verify application functionality
+docker compose exec app python manage.py check
+```
+
+#### Step 5: Restart Services
+```bash
+# Restart application
+docker compose restart app
+
+# Restart all services (if needed)
+docker compose restart
+```
+
+## Troubleshooting
+
+### Migration Failure Recovery
+
+```bash
+# 1. Clean up with migration_simple_reset.py
+docker compose exec app python migration_simple_reset.py --reset-only
+
+# 2. Manually check migration status
+docker compose exec app python manage.py showmigrations
+
+# 3. Apply individual migrations if needed
+docker compose exec app python manage.py migrate rog 0001 --fake
+```
+
+### Restore from Backup
+
+```bash
+# Database restoration
+docker compose exec postgres-db psql -U admin -d rogaining_db < backup_file.sql
+
+# Migration files restoration
+rm -rf rog/migrations
+cp -r rog/migrations_backup_deploy_YYYYMMDD_HHMMSS rog/migrations
+```
+
+## Important Considerations
+
+### ✅ Pre-execution Checklist
+- [ ] Database backup created
+- [ ] Migration files backup created
+- [ ] migration_simple_reset.py is latest version
+- [ ] Docker environment running normally
+- [ ] Sufficient disk space available
+
+### ⚠️ Operations to Avoid
+- Running `python manage.py migrate` first (causes dependency errors)
+- Working without backups
+- Experimental operations in production environment
+
+### 🔄 Rollback Plan
+```bash
+# Emergency restoration when issues occur
+docker compose down
+docker compose exec postgres-db psql -U admin -d rogaining_db < backup_file.sql
+cp -r rog/migrations_backup_deploy_YYYYMMDD_HHMMSS rog/migrations
+docker compose up -d
+```
+
+## Summary
+
+**Recommended Final Procedure:**
+
+```bash
+# 1. Create backup
+pg_dump rogaining_db > backup_$(date +%Y%m%d_%H%M%S).sql
+
+# 2. Get latest code
+git pull origin main
+
+# 3. Batch migration reset (avoids issues)
+docker compose exec app python migration_simple_reset.py --full
+
+# 4. Verify functionality
+docker compose exec app python manage.py check
+docker compose restart app
+```
+
+This procedure avoids migration dependency issues and enables safe deployment.
+
+## Command Reference
+
+### migration_simple_reset.py Options
+
+```bash
+# Complete workflow
+python migration_simple_reset.py --full
+
+# Backup only
+python migration_simple_reset.py --backup-only
+
+# Reset only (requires existing backup)
+python migration_simple_reset.py --reset-only
+
+# Apply only (requires simple migration to exist)
+python migration_simple_reset.py --apply-only
+```
+
+### Docker Compose Commands
+
+```bash
+# Check service status
+docker compose ps
+
+# Execute commands in app container
+docker compose exec app [command]
+
+# Execute commands in database container
+docker compose exec postgres-db [command]
+
+# Restart specific service
+docker compose restart [service_name]
+
+# View logs
+docker compose logs [service_name]
+```
+
+### Database Operations
+
+```bash
+# Create database backup
+docker compose exec postgres-db pg_dump -U admin rogaining_db > backup.sql
+
+# Restore database
+docker compose exec postgres-db psql -U admin -d rogaining_db < backup.sql
+
+# Connect to database shell
+docker compose exec postgres-db psql -U admin -d rogaining_db
+```
+
+## Error Scenarios and Solutions
+
+### Scenario 1: Migration Dependency Error
+**Error**: `NodeNotFoundError: Migration rog.0010_auto_20250827_1510 dependencies reference nonexistent parent node`
+
+**Solution**:
+```bash
+docker compose exec app python migration_simple_reset.py --full
+```
+
+### Scenario 2: Database Connection Error
+**Error**: Database connection issues during migration
+
+**Solution**:
+```bash
+# Check database status
+docker compose ps postgres-db
+
+# Restart database if needed
+docker compose restart postgres-db
+
+# Wait for database to be ready
+docker compose exec postgres-db pg_isready -U admin
+```
+
+### Scenario 3: Disk Space Issues
+**Error**: Insufficient disk space during backup or migration
+
+**Solution**:
+```bash
+# Check disk usage
+df -h
+
+# Clean up Docker resources
+docker system prune
+
+# Remove old backups if safe
+rm old_backup_files.sql
+```
+
+### Scenario 4: Permission Issues
+**Error**: Permission denied when executing scripts
+
+**Solution**:
+```bash
+# Make script executable
+chmod +x migration_simple_reset.py
+
+# Check file ownership
+ls -la migration_simple_reset.py
+
+# Fix ownership if needed
+chown user:group migration_simple_reset.py
+```
+
+## Best Practices
+
+### 1. Always Create Backups
+- Database backup before any migration operation
+- Migration files backup for rollback capability
+- Configuration files backup
+
+### 2. Test in Staging Environment
+- Verify the migration procedure in staging first
+- Test with production-like data volume
+- Validate application functionality after migration
+
+### 3. Monitor During Deployment
+- Watch container logs during migration
+- Monitor database performance
+- Check application health endpoints
+
+### 4. Document Changes
+- Record migration procedure execution
+- Note any deviations from standard procedure
+- Update deployment documentation
+
+### 5. Plan for Rollback
+- Have clear rollback procedures ready
+- Test rollback in staging environment
+- Ensure backups are valid and accessible
+
+This guide ensures safe and reliable deployment of the rogaining_srv application with proper migration handling.