ai_qc/DEPLOYMENT_STEPS.md

AI QC Deployment Steps - From /opt/ai_qc

Current Status ✅

You've already completed:

• Cloned repository to /opt/ai_qc
• Created virtual environment in /opt/ai_qc/venv
• 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:

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

Ensure these paths are set (add if missing):

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 🔒

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

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

[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)

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

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

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

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

Add this configuration:

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

sudo a2enmod proxy proxy_http alias

Enable the site:

sudo a2ensite ai_qc.conf

Test Apache configuration:

sudo apache2ctl configtest
# Should return "Syntax OK"

Reload Apache:

sudo systemctl reload apache2

Step 7: Verify Everything Works 🎯

Check Backend Service

# Service should be running
sudo systemctl status ai_qc

# Should show "active (running)"

Check Backend API Directly

# Test API endpoint
curl http://localhost:7183/api/profiles

# Should return JSON with profiles

Check Through Apache

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

# 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

# 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

# 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

# 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

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

# 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. 🚀