ai_qc/DEPLOYMENT_STEPS.md

# AI QC Deployment Steps - From /opt/ai_qc

## Current Status ✅

You've already completed:
- [x] Cloned repository to `/opt/ai_qc`
- [x] Created virtual environment in `/opt/ai_qc/venv`
- [x] Installed requirements from requirements.txt

Good news: You're already 50% done! 🎉

---

## Repository Structure in /opt/ai_qc

```
/opt/ai_qc/
├── frontend/               # Frontend files
│   └── index.html
├── backend/               # Backend files
│   ├── api_server.py
│   ├── run_api_server.py
│   ├── visual_qc_apps/
│   ├── profiles/
│   └── ... (all backend code)
├── venv/                  # Your virtual environment
└── ... (other repo files)
```

---

## Remaining Steps

### Step 1: Update Backend Configuration ⚙️

Update the production environment config with absolute paths:

```bash
# On your server
cd /opt/ai_qc
nano backend/config/production.env
```

Ensure these paths are set (add if missing):
```bash
ENVIRONMENT=production
UPLOAD_FOLDER=/opt/ai_qc/backend/uploads
OUTPUT_FOLDER=/opt/ai_qc/backend/output
UPLOAD_FOLDER_DEV=/opt/ai_qc/backend/uploads-dev
OUTPUT_FOLDER_DEV=/opt/ai_qc/backend/output-dev
BRAND_GUIDELINES_FOLDER=/opt/ai_qc/backend/brand_guidelines

# Your API keys (should already be set)
OPENAI_API_KEY=your_key_here
GOOGLE_API_KEY=your_key_here
AZURE_TENANT_ID=your_tenant_id
AZURE_CLIENT_ID=your_client_id
SECRET_KEY=your_secret_key
```

Save and exit (Ctrl+X, Y, Enter)

### Step 2: Set Correct Permissions 🔒

```bash
# Set ownership
sudo chown -R www-data:www-data /opt/ai_qc

# Set base permissions
sudo chmod -R 750 /opt/ai_qc

# Ensure data directories are writable
sudo chmod 770 /opt/ai_qc/backend/uploads
sudo chmod 770 /opt/ai_qc/backend/uploads-dev
sudo chmod 770 /opt/ai_qc/backend/output
sudo chmod 770 /opt/ai_qc/backend/output-dev

# Protect config files
sudo chmod 640 /opt/ai_qc/backend/config/*.env
```

### Step 3: Update and Install Systemd Service 🔧

```bash
# Copy the updated service file from the repo
sudo cp /opt/ai_qc/ai_qc_updated.service /etc/systemd/system/ai_qc.service

# Or manually edit the existing one
sudo nano /etc/systemd/system/ai_qc.service
```

**Updated service file content:**
```ini
[Unit]
Description=AI QC service
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/opt/ai_qc/backend
ExecStart=/opt/ai_qc/venv/bin/python /opt/ai_qc/backend/run_api_server.py --host localhost --port 7183 --workers 2
Restart=on-failure
RestartSec=5s
Environment=ENVIRONMENT=production
Environment="PYTHONPATH=/opt/ai_qc/backend"

[Install]
WantedBy=multi-user.target
```

**Key changes:**
- `WorkingDirectory=/opt/ai_qc/backend` (was `/var/www/html/ai_qc`)
- `ExecStart=/opt/ai_qc/venv/bin/python /opt/ai_qc/backend/run_api_server.py` (points to backend folder)
- Added `PYTHONPATH=/opt/ai_qc/backend` (helps Python find modules)

```bash
# Reload systemd to pick up changes
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable ai_qc

# Start the service
sudo systemctl start ai_qc

# Check status
sudo systemctl status ai_qc
```

### Step 4: Test Backend API 🧪

```bash
# Test if backend is responding
curl http://localhost:7183/api/profiles

# Should return JSON with available profiles
# If you get an error, check logs:
sudo journalctl -u ai_qc -n 50 --no-pager
```

### Step 5: Deploy Frontend to Web Root 🌐

```bash
# Copy frontend file to web root
sudo mkdir -p /var/www/html/ai_qc
sudo cp /opt/ai_qc/frontend/index.html /var/www/html/ai_qc/

# Set ownership
sudo chown -R www-data:www-data /var/www/html/ai_qc
```

### Step 6: Configure Apache Reverse Proxy 🔄

Create or update Apache configuration:

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

Add this configuration:
```apache
<VirtualHost *:80>
    # Update with your actual domain
    ServerName your-domain.com

    # Frontend - serve from web root
    DocumentRoot /var/www/html/ai_qc

    <Directory /var/www/html/ai_qc>
        Options -Indexes +FollowSymLinks
        AllowOverride None
        Require all granted
        DirectoryIndex index.html
    </Directory>

    # Backend API - proxy to Flask on port 7183
    ProxyPreserveHost On

    # Handle both /api and /ai_qc/api patterns
    ProxyPass /ai_qc/api http://localhost:7183/api
    ProxyPassReverse /ai_qc/api http://localhost:7183/api

    ProxyPass /api http://localhost:7183/api
    ProxyPassReverse /api http://localhost:7183/api

    ProxyTimeout 300

    # Serve uploads from backend location
    Alias /uploads /opt/ai_qc/backend/uploads
    <Directory /opt/ai_qc/backend/uploads>
        Options -Indexes
        Require all granted
    </Directory>

    # Serve output from backend location
    Alias /output /opt/ai_qc/backend/output
    <Directory /opt/ai_qc/backend/output>
        Options -Indexes
        Require all granted
    </Directory>

    # Development folders (optional - remove in production)
    Alias /uploads-dev /opt/ai_qc/backend/uploads-dev
    <Directory /opt/ai_qc/backend/uploads-dev>
        Options -Indexes
        Require all granted
    </Directory>

    Alias /output-dev /opt/ai_qc/backend/output-dev
    <Directory /opt/ai_qc/backend/output-dev>
        Options -Indexes
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/ai_qc_error.log
    CustomLog ${APACHE_LOG_DIR}/ai_qc_access.log combined
</VirtualHost>
```

**Enable required Apache modules:**
```bash
sudo a2enmod proxy proxy_http alias
```

**Enable the site:**
```bash
sudo a2ensite ai_qc.conf
```

**Test Apache configuration:**
```bash
sudo apache2ctl configtest
# Should return "Syntax OK"
```

**Reload Apache:**
```bash
sudo systemctl reload apache2
```

### Step 7: Verify Everything Works 🎯

#### Check Backend Service
```bash
# Service should be running
sudo systemctl status ai_qc

# Should show "active (running)"
```

#### Check Backend API Directly
```bash
# Test API endpoint
curl http://localhost:7183/api/profiles

# Should return JSON with profiles
```

#### Check Through Apache
```bash
# Test frontend
curl http://your-domain.com/

# Should return HTML content

# Test API through Apache proxy
curl http://your-domain.com/api/profiles

# Should return same JSON as direct test
```

#### Check in Browser
1. Open `http://your-domain.com/` in browser
2. Should see the Visual AI QC interface
3. Click "Sign In with Microsoft"
4. Authenticate with Azure AD
5. Try uploading a test file and running analysis
6. Verify results display correctly

### Step 8: Monitor Logs 📊

Keep an eye on logs for the first hour:

```bash
# Backend service logs (real-time)
sudo journalctl -u ai_qc -f

# Apache error log
sudo tail -f /var/log/apache2/ai_qc_error.log

# Apache access log
sudo tail -f /var/log/apache2/ai_qc_access.log
```

---

## Quick Troubleshooting 🔧

### Backend Service Won't Start
```bash
# Check logs
sudo journalctl -u ai_qc -n 50 --no-pager

# Try running manually to see errors
cd /opt/ai_qc/backend
sudo -u www-data /opt/ai_qc/venv/bin/python run_api_server.py --host localhost --port 7183 --workers 2
```

**Common issues:**
- **Module not found**: Check PYTHONPATH in service file
- **Permission denied**: Check file ownership and permissions
- **Port already in use**: Check if old service is still running

### API Returns 404
```bash
# Check if service is running
sudo systemctl status ai_qc

# Check if port 7183 is listening
sudo ss -tlnp | grep 7183

# Test direct connection
curl -v http://localhost:7183/api/profiles
```

### Frontend Shows But API Fails
```bash
# Check Apache proxy configuration
sudo apache2ctl -S

# Check Apache error log
sudo tail -50 /var/log/apache2/ai_qc_error.log

# Verify proxy modules are enabled
apache2ctl -M | grep proxy
```

### File Upload Fails
```bash
# Check directory permissions
ls -la /opt/ai_qc/backend/uploads
ls -la /opt/ai_qc/backend/output

# Should be owned by www-data with 770 permissions
sudo chmod 770 /opt/ai_qc/backend/uploads /opt/ai_qc/backend/output
sudo chown www-data:www-data /opt/ai_qc/backend/uploads /opt/ai_qc/backend/output
```

---

## Rollback Plan 🔄

If you need to rollback to the old setup at `/var/www/html/ai_qc`:

```bash
# Stop new service
sudo systemctl stop ai_qc

# Restore old service file
sudo cp /etc/systemd/system/ai_qc.service.backup /etc/systemd/system/ai_qc.service
sudo systemctl daemon-reload

# Start old service
sudo systemctl start ai_qc

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

---

## Summary of Changes

### What Changed
- ✅ Backend now runs from `/opt/ai_qc/backend/` (not `/var/www/html/ai_qc/`)
- ✅ Frontend served from `/var/www/html/ai_qc/index.html`
- ✅ Virtual environment at `/opt/ai_qc/venv/`
- ✅ Apache proxies API requests to backend

### What Stayed The Same
- ✅ Backend runs on port 7183 (localhost only)
- ✅ Same 2 workers
- ✅ Same restart policy
- ✅ Still runs as www-data user

### Benefits
- ✅ Backend code not in web-accessible directory
- ✅ Follows server standard pattern (`/opt/`)
- ✅ Better security and separation
- ✅ Easier to maintain and update

---

## Final Checklist ✅

Before considering deployment complete:

- [ ] Backend config updated (`backend/config/production.env`)
- [ ] Permissions set correctly on `/opt/ai_qc`
- [ ] Systemd service file updated and installed
- [ ] Service starts successfully (`systemctl status ai_qc`)
- [ ] Backend API responds (`curl http://localhost:7183/api/profiles`)
- [ ] Frontend copied to `/var/www/html/ai_qc/`
- [ ] Apache configuration updated
- [ ] Apache reloaded without errors
- [ ] Frontend loads in browser
- [ ] API calls work through Apache proxy
- [ ] Authentication works (Microsoft sign-in)
- [ ] File upload works
- [ ] Analysis runs successfully
- [ ] Results display correctly
- [ ] Logs show no errors

---

## Need Help?

If you encounter issues:

1. **Check service logs**: `sudo journalctl -u ai_qc -n 100 --no-pager`
2. **Check Apache logs**: `sudo tail -100 /var/log/apache2/ai_qc_error.log`
3. **Test backend directly**: `curl http://localhost:7183/api/profiles`
4. **Verify permissions**: `ls -la /opt/ai_qc/backend/`
5. **Check config**: `cat /opt/ai_qc/backend/config/production.env`

Share the output and I can help troubleshoot!

---

**You're almost there!** Follow these steps and you'll have a clean, properly deployed application. 🚀