ai_qc/DEV_PROD_SETUP.md

Development & Production Environment Setup

This guide explains how to use the new development and production environment setup for the Visual AI QC application.

Quick Start

1. Azure AD Setup (One-time)

• Go to Azure Portal → Azure Active Directory → App registrations
• Create new registration: "Visual AI QC - Development"
• Set redirect URI: http://localhost:7183 (SPA type)
• Copy the client ID and update config/development.env

2. Update Development Config

Edit config/development.env and replace:

AZURE_CLIENT_ID=REPLACE-WITH-YOUR-NEW-DEV-CLIENT-ID

3. Run Local Development

# Start development server
./scripts/run-local.sh

# Or manually
export ENVIRONMENT=development
python api_server.py

Access at: http://localhost:7183

4. Deploy to Production

# Test first
./scripts/test-system.sh

# Deploy to production
./scripts/deploy-to-prod.sh

Environment Structure

config/
├── development.env    # Local development settings
├── production.env     # Production server settings
└── .env.template      # Template for new environments

uploads-dev/          # Development uploads (separate from production)
output-dev/           # Development output (separate from production)

scripts/
├── run-local.sh      # Start local development
├── deploy-to-prod.sh # Deploy to production  
└── test-system.sh    # Validate system before deployment

Configuration Details

Development Environment

• Port: 7183 (same as before for consistency)
• Folders: uploads-dev/, output-dev/
• Azure AD: Separate app registration for localhost
• Debug: Enabled
• API Keys: Same as production (or separate if preferred)

Production Environment

• Port: 7184 (or configured port)
• Folders: uploads/, output/ (existing)
• Azure AD: Existing production registration
• Debug: Disabled
• API Keys: Existing production keys

Development Workflow

Making Changes Locally

1. Start development server: ./scripts/run-local.sh
2. Make your changes to the code
3. Test locally at http://localhost:7183
4. Run validation: ./scripts/test-system.sh
5. Deploy when ready: ./scripts/deploy-to-prod.sh

Benefits of This Setup

• ✅ Safe Testing: Changes don't affect production
• ✅ Separate Data: Dev uploads/output don't mix with production
• ✅ Easy Deployment: One command to push to production
• ✅ Automated Testing: Validation before deployment
• ✅ Quick Rollback: Automatic backups before deployment

Environment Detection

The application automatically detects which environment to use based on:

1. ENVIRONMENT environment variable (development/production)
2. Config file existence in config/ folder
3. Fallback to legacy config.env if new structure not found

Scripts Overview

run-local.sh

• Sets environment to development
• Starts server on port 7183
• Uses development config and folders
• Activates virtual environment if available

deploy-to-prod.sh

• Runs pre-deployment tests
• Creates production backup
• Syncs files to production server
• Restarts production service
• Note: Update server details in script

test-system.sh

• Python syntax validation
• Core module import testing
• Profile system validation
• QC module testing
• Configuration validation
• Brand guidelines database testing

Troubleshooting

"Config file not found"

• Ensure config/development.env exists
• Check AZURE_CLIENT_ID is set correctly
• Verify Azure AD app registration created

"Authentication not working"

• Check Azure AD redirect URI: http://localhost:7183
• Verify client ID in development config
• Clear browser cache/cookies

"Tests failing"

• Run individual tests: python -c "import api_server"
• Check virtual environment activated
• Verify all dependencies installed

Migration Notes

This setup is backward compatible:

• Existing config.env still works
• Production behavior unchanged
• No disruption to current production setup

The application will automatically use the new environment system when config/ folder is detected, otherwise falls back to the original config.env setup.