ai_qc/backend/MIGRATION_CHECKLIST.md

Migration Day Checklist ✅

Use this checklist during your migration to track progress and ensure nothing is missed.

---

Pre-Migration (30 minutes before)

• Read Complete Documentation

  • Read MIGRATION_GUIDE.md completely
  • Review MIGRATION_SUMMARY.md for quick reference
  • Understand rollback procedure

• Prepare Environment

  • SSH access to server confirmed
  • Sudo privileges verified
  • Backup directory prepared (~/backups/)
  • Maintenance window scheduled and communicated

• Verify Current State

  # Run these commands to document current state:
  sudo systemctl status ai_qc | tee ~/pre-migration-service-status.txt
  ps aux | grep run_api_server.py | tee ~/pre-migration-process.txt
  ls -la /var/www/html/ai_qc/ | tee ~/pre-migration-files.txt
  

---

Migration Steps (20-30 minutes)

Step 1: Backup ✅

• Create backup of current deployment

  cd /var/www/html/ai_qc
  sudo tar -czf ~/ai_qc_backup_$(date +%Y%m%d_%H%M%S).tar.gz .
  ls -lh ~/ai_qc_backup_*.tar.gz  # Verify backup created
  

• Backup created successfully
• Backup size looks reasonable (should be several MB)
• Backup location noted: _______________

Step 2: Stop Current Service ✅

• Find service name

  sudo systemctl list-units --type=service | grep ai_qc
  

• Service name identified: _______________
• Stop the service

  sudo systemctl stop [SERVICE_NAME]
  

• Verify service stopped

  sudo systemctl status ai_qc
  ps aux | grep run_api_server.py  # Should return nothing
  

• Service fully stopped (no processes running)

Step 3: Create Backend Directory ✅

• Create /opt/ai_qc/ directory

  sudo mkdir -p /opt/ai_qc
  

• Copy files to backend location

  cd /var/www/html/ai_qc
  sudo rsync -av \
    --exclude='web_ui.html' \
    --exclude='*.pyc' \
    --exclude='__pycache__' \
    --exclude='.git' \
    . /opt/ai_qc/
  

• Verify files copied

  ls -la /opt/ai_qc/  # Should see all Python files
  

• Set ownership

  sudo chown -R www-data:www-data /opt/ai_qc
  

• Set permissions

  sudo chmod -R 750 /opt/ai_qc
  sudo chmod 770 /opt/ai_qc/uploads /opt/ai_qc/output
  sudo chmod 770 /opt/ai_qc/uploads-dev /opt/ai_qc/output-dev
  sudo chmod 640 /opt/ai_qc/config/*.env
  

Step 4: Prepare Frontend ✅

• Create new frontend directory

  sudo mkdir -p /var/www/html/ai_qc_new
  

• Copy and rename web_ui.html

  sudo cp /var/www/html/ai_qc/web_ui.html /var/www/html/ai_qc_new/index.html
  

• Set ownership

  sudo chown -R www-data:www-data /var/www/html/ai_qc_new
  

• Verify frontend file exists

  ls -la /var/www/html/ai_qc_new/index.html
  

Step 5: Update Backend Paths ✅

• Edit production.env

  sudo nano /opt/ai_qc/config/production.env
  

• Verify paths are absolute (start with /opt/ai_qc/)
  • UPLOAD_FOLDER=/opt/ai_qc/uploads
  • OUTPUT_FOLDER=/opt/ai_qc/output
  • UPLOAD_FOLDER_DEV=/opt/ai_qc/uploads-dev
  • OUTPUT_FOLDER_DEV=/opt/ai_qc/output-dev
  • BRAND_GUIDELINES_FOLDER=/opt/ai_qc/brand_guidelines
• Save and exit

Step 6: Update Systemd Service ✅

• Backup existing service file

  sudo cp /etc/systemd/system/ai_qc.service /etc/systemd/system/ai_qc.service.backup
  

• Edit service file

  sudo nano /etc/systemd/system/ai_qc.service
  

• Verify key settings:
  • WorkingDirectory=/opt/ai_qc
  • ExecStart=/opt/ai_qc/venv/bin/python /opt/ai_qc/run_api_server.py ...
  • User=www-data
  • Group=www-data
• Save and exit
• Reload systemd

  sudo systemctl daemon-reload
  

Step 7: Install Dependencies ✅

• Activate virtual environment

  cd /opt/ai_qc
  source venv/bin/activate
  

• Install waitress

  pip install waitress
  

• Verify requirements

  pip install -r requirements.txt
  

• Deactivate venv

  deactivate
  

Step 8: Test Backend Standalone ✅

• Test backend starts

  cd /opt/ai_qc
  sudo -u www-data /opt/ai_qc/venv/bin/python run_api_server.py --host localhost --port 7183 --workers 2
  

• Backend server started without errors
• In another terminal, test API

  curl http://localhost:7183/api/profiles
  

• API response received (should show profiles JSON)
• Stop test server (Ctrl+C)

Step 9: Update Apache Configuration ✅

• Backup current Apache config

  sudo cp /etc/apache2/sites-available/ai_qc.conf /etc/apache2/sites-available/ai_qc.conf.backup
  

• Edit Apache config

  sudo nano /etc/apache2/sites-available/ai_qc.conf
  

• Update key sections:
  • DocumentRoot points to /var/www/html/ai_qc_new
  • ProxyPass /api and /ai_qc/api configured
  • Alias /uploads points to /opt/ai_qc/uploads
  • Alias /output points to /opt/ai_qc/output
• Save and exit
• Test Apache config

  sudo apache2ctl configtest
  

• Apache config test result: Syntax OK

Step 10: Start Services ✅

• Start backend service

  sudo systemctl start ai_qc
  

• Check service status

  sudo systemctl status ai_qc
  

• Service running successfully (active/running)
• Check logs for errors

  sudo journalctl -u ai_qc -n 50 --no-pager
  

• No critical errors in logs
• Verify backend responds

  curl http://localhost:7183/api/profiles
  

• Backend API responding correctly

Step 11: Reload Apache ✅

• Reload Apache

  sudo systemctl reload apache2
  

• Check Apache status

  sudo systemctl status apache2
  

• Apache reloaded successfully
• Check Apache errors

  sudo tail -20 /var/log/apache2/ai_qc_error.log
  

• No critical Apache errors

---

Testing (10 minutes)

Browser Testing ✅

• Open application URL: _______________
• Frontend loads correctly
• No console errors (F12 → Console tab)
• "Sign In with Microsoft" button visible
• Click sign in and authenticate
• Authentication successful
• User name displayed in UI

Functionality Testing ✅

• Upload test file successfully
• Select profile from dropdown
• Start analysis
• Progress updates appear in real-time
• Analysis completes successfully
• Results display correctly
• Overall score shown
• Individual check results visible
• Download report button works
• Saved files list updates automatically
• New file highlighted in saved files list

Additional Testing ✅

• Test different profile (e.g., General Check)
• Test with reference asset selection
• Test JSON output mode
• Verify JSON download works
• Test sign out functionality
• Test sign in again

---

Finalization (5 minutes)

Directory Cleanup ✅

• Rename old directory

  sudo mv /var/www/html/ai_qc /var/www/html/ai_qc_old
  

• Rename new directory

  sudo mv /var/www/html/ai_qc_new /var/www/html/ai_qc
  

• Update Apache config DocumentRoot (if needed)

  sudo nano /etc/apache2/sites-available/ai_qc.conf
  # Change: DocumentRoot /var/www/html/ai_qc_new
  # To:     DocumentRoot /var/www/html/ai_qc
  

• Reload Apache

  sudo systemctl reload apache2
  

• Test application still works after rename

Enable Service on Boot ✅

• Enable service

  sudo systemctl enable ai_qc
  

• Verify enabled

  sudo systemctl is-enabled ai_qc
  

• Result shows "enabled"

Documentation ✅

• Document migration completion time: _______________
• Note any issues encountered: _______________
• Record backup location: _______________
• Save this checklist for reference

---

Post-Migration Monitoring (24 hours)

Immediate Monitoring (First Hour) ✅

• Monitor logs every 10 minutes

  sudo journalctl -u ai_qc -f
  

• Check for errors or warnings
• Test multiple analyses
• Verify all features working

Day 1 Monitoring ✅

• Check service status multiple times

  sudo systemctl status ai_qc
  

• Review logs for any anomalies

  sudo journalctl -u ai_qc -n 200 --no-pager
  

• Check disk space

  df -h /opt/ai_qc
  

• Verify uploads and outputs working

After 48 Hours ✅

• Confirm no issues reported by users
• Review system logs one final time
• Remove old directory (optional)

  sudo rm -rf /var/www/html/ai_qc_old
  

• Keep backup for 30 days before deleting

---

Rollback Procedure (If Needed) 🚨

Quick Rollback Steps

If issues occur and you need to rollback immediately:

1. Stop New Service

   sudo systemctl stop ai_qc
   

2. Restore Old Directory

   sudo mv /var/www/html/ai_qc /var/www/html/ai_qc_failed
   sudo mv /var/www/html/ai_qc_old /var/www/html/ai_qc
   

3. Restore Old Apache Config

   sudo cp /etc/apache2/sites-available/ai_qc.conf.backup /etc/apache2/sites-available/ai_qc.conf
   sudo systemctl reload apache2
   

4. Restore Old Service File

   sudo cp /etc/systemd/system/ai_qc.service.backup /etc/systemd/system/ai_qc.service
   sudo systemctl daemon-reload
   

5. Start Old Service

   sudo systemctl start ai_qc
   

6. Verify Old Version Works

   curl http://your-domain.com/
   

---

Migration Summary

Migration Date: _______________ Started: _______________ Completed: _______________ Total Duration: _______________

Services Involved:

• Backend Service: _______________
• Web Server: Apache2
• Working: ✅ / ❌

Issues Encountered:

Write any issues or notes here:

Final Status:

• ✅ Migration Successful - All features working
• ⚠️ Migration Partial - Some issues to resolve
• ❌ Migration Failed - Rolled back to original

Sign-off: _______________ (Name and Date)

---

Notes and Reminders

• Keep backup for at least 30 days before deleting
• Monitor logs for first week after migration
• Update any deployment documentation with new paths
• Inform team of new directory structure
• Update any automation scripts pointing to old paths

---

End of Migration Checklist ✨