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**
  ```bash
  # 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
  ```bash
  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
  ```bash
  sudo systemctl list-units --type=service | grep ai_qc
  ```
- [ ] Service name identified: `_______________`
- [ ] Stop the service
  ```bash
  sudo systemctl stop [SERVICE_NAME]
  ```
- [ ] Verify service stopped
  ```bash
  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
  ```bash
  sudo mkdir -p /opt/ai_qc
  ```
- [ ] Copy files to backend location
  ```bash
  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
  ```bash
  ls -la /opt/ai_qc/  # Should see all Python files
  ```
- [ ] Set ownership
  ```bash
  sudo chown -R www-data:www-data /opt/ai_qc
  ```
- [ ] Set permissions
  ```bash
  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
  ```bash
  sudo mkdir -p /var/www/html/ai_qc_new
  ```
- [ ] Copy and rename web_ui.html
  ```bash
  sudo cp /var/www/html/ai_qc/web_ui.html /var/www/html/ai_qc_new/index.html
  ```
- [ ] Set ownership
  ```bash
  sudo chown -R www-data:www-data /var/www/html/ai_qc_new
  ```
- [ ] Verify frontend file exists
  ```bash
  ls -la /var/www/html/ai_qc_new/index.html
  ```

### Step 5: Update Backend Paths ✅
- [ ] Edit production.env
  ```bash
  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
  ```bash
  sudo cp /etc/systemd/system/ai_qc.service /etc/systemd/system/ai_qc.service.backup
  ```
- [ ] Edit service file
  ```bash
  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
  ```bash
  sudo systemctl daemon-reload
  ```

### Step 7: Install Dependencies ✅
- [ ] Activate virtual environment
  ```bash
  cd /opt/ai_qc
  source venv/bin/activate
  ```
- [ ] Install waitress
  ```bash
  pip install waitress
  ```
- [ ] Verify requirements
  ```bash
  pip install -r requirements.txt
  ```
- [ ] Deactivate venv
  ```bash
  deactivate
  ```

### Step 8: Test Backend Standalone ✅
- [ ] Test backend starts
  ```bash
  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
  ```bash
  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
  ```bash
  sudo cp /etc/apache2/sites-available/ai_qc.conf /etc/apache2/sites-available/ai_qc.conf.backup
  ```
- [ ] Edit Apache config
  ```bash
  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
  ```bash
  sudo apache2ctl configtest
  ```
- [ ] Apache config test result: Syntax OK

### Step 10: Start Services ✅
- [ ] Start backend service
  ```bash
  sudo systemctl start ai_qc
  ```
- [ ] Check service status
  ```bash
  sudo systemctl status ai_qc
  ```
- [ ] Service running successfully (active/running)
- [ ] Check logs for errors
  ```bash
  sudo journalctl -u ai_qc -n 50 --no-pager
  ```
- [ ] No critical errors in logs
- [ ] Verify backend responds
  ```bash
  curl http://localhost:7183/api/profiles
  ```
- [ ] Backend API responding correctly

### Step 11: Reload Apache ✅
- [ ] Reload Apache
  ```bash
  sudo systemctl reload apache2
  ```
- [ ] Check Apache status
  ```bash
  sudo systemctl status apache2
  ```
- [ ] Apache reloaded successfully
- [ ] Check Apache errors
  ```bash
  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
  ```bash
  sudo mv /var/www/html/ai_qc /var/www/html/ai_qc_old
  ```
- [ ] Rename new directory
  ```bash
  sudo mv /var/www/html/ai_qc_new /var/www/html/ai_qc
  ```
- [ ] Update Apache config DocumentRoot (if needed)
  ```bash
  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
  ```bash
  sudo systemctl reload apache2
  ```
- [ ] Test application still works after rename

### Enable Service on Boot ✅
- [ ] Enable service
  ```bash
  sudo systemctl enable ai_qc
  ```
- [ ] Verify enabled
  ```bash
  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
  ```bash
  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
  ```bash
  sudo systemctl status ai_qc
  ```
- [ ] Review logs for any anomalies
  ```bash
  sudo journalctl -u ai_qc -n 200 --no-pager
  ```
- [ ] Check disk space
  ```bash
  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)
  ```bash
  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**
   ```bash
   sudo systemctl stop ai_qc
   ```

2. **Restore Old Directory**
   ```bash
   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**
   ```bash
   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**
   ```bash
   sudo cp /etc/systemd/system/ai_qc.service.backup /etc/systemd/system/ai_qc.service
   sudo systemctl daemon-reload
   ```

5. **Start Old Service**
   ```bash
   sudo systemctl start ai_qc
   ```

6. **Verify Old Version Works**
   ```bash
   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** ✨