Skip to main content

Environment Management Guide

This guide explains how to manage development and production environments for the Agentification Platform.

🏗️ Environment Architecture​

Development Environment​

  • Frontend: Vite dev server with hot reloading
  • Backend: Flask with debug mode
  • Database: SQLite (local file-based)
  • Features: Full debugging, API proxy, development tools

Production Environment​

  • Frontend: Vercel static hosting (optimized build)
  • Backend: Vercel serverless functions (Flask)
  • Database: Supabase PostgreSQL
  • Features: Optimized, secure, scalable

🚀 Quick Start​

Development Setup​

# Set up development environment
./env-manager.sh dev

# Start development servers
./dev.sh

Production Setup​

# Set up production environment
./env-manager.sh prod

# Edit .env with your actual production values
# Then test locally
./prod.sh

# Deploy to Vercel
npm run build
git add .
git commit -m "Production deployment"
git push origin main

📋 Environment Commands​

Environment Manager​

./env-manager.sh dev       # Switch to development
./env-manager.sh prod      # Switch to production
./env-manager.sh status    # Check current status
./env-manager.sh clean     # Clean environment files

Development Scripts​

./dev.sh                   # Start both frontend & backend
npm run dev               # Frontend only (Vite)
npm run flask:dev         # Backend only (Flask)

Production Scripts​

./prod.sh                  # Test production build locally
npm run build             # Build for production
npm run preview           # Preview production build

⚙️ Environment Configuration​

Development Environment Variables (env.development)​

# Environment
NODE_ENV=development
FLASK_ENV=development

# Database (SQLite for fast local development)
DATABASE_URL=sqlite:///database/app.db

# Flask Configuration
SECRET_KEY=dev-secret-key-change-in-production
JWT_SECRET=dev-jwt-secret-key-change-in-production

# Supabase (Optional - can use test project)
VITE_SUPABASE_URL=https://your-dev-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-dev-anon-key

# Development Features
DEBUG=true
EMAIL_ENABLED=false  # Logs to console instead of sending
CORS_ORIGINS=http://localhost:3000,http://localhost:5001

Production Environment Variables (env.production)​

# Environment
NODE_ENV=production
FLASK_ENV=production

# Database (Supabase PostgreSQL)
DATABASE_URL=postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:5432/postgres

# Flask Configuration
SECRET_KEY=your-production-secret-key-here
JWT_SECRET=your-production-jwt-secret-here

# Supabase (Production Project)
VITE_SUPABASE_URL=https://your-prod-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-prod-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-prod-service-role-key

# Production Features
DEBUG=false
EMAIL_ENABLED=true
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password

🔄 Environment Switching​

Switch to Development​

./env-manager.sh dev
# This copies env.development to .env
# Sets NODE_ENV=development

Switch to Production​

./env-manager.sh prod
# This copies env.production to .env
# Remember to set actual values!

Check Current Status​

./env-manager.sh status
# Shows current environment variables
# Indicates what's configured vs template values

🗄️ Database Management​

Development Database (SQLite)​

  • File: database/app.db
  • Auto-created: When you run the Flask app
  • Reset: Delete the file to start fresh

Production Database (Supabase)​

  • Setup: Run schema.sql in Supabase dashboard
  • Migration: npm run db:migrate
  • Connection: Via DATABASE_URL environment variable

🔧 Development Workflow​

Daily Development​

# Start fresh development environment
./env-manager.sh dev
./dev.sh

# Frontend: http://localhost:3000
# Backend: http://localhost:5001
# API calls proxy automatically

Testing Production Build​

# Switch to production config
./env-manager.sh prod

# Edit .env with production values
# Test production build locally
./prod.sh

# Frontend: http://localhost:4173 (production build)
# Backend: Still http://localhost:5001 (Flask)

Database Operations​

# Migrate data to Supabase
npm run db:migrate

# Reset development database
rm database/app.db
npm run flask:dev  # Recreate tables

🚀 Deployment Workflow​

Deploy to Vercel​

# Ensure production environment
./env-manager.sh prod

# Build and commit
npm run build
git add .
git commit -m "Production deployment"
git push origin main

# Vercel automatically deploys
# Set environment variables in Vercel dashboard

Vercel Environment Variables​

Set these in your Vercel project settings:

NODE_ENV=production
DATABASE_URL=postgresql://...
VITE_SUPABASE_URL=https://...
VITE_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...
SECRET_KEY=...
JWT_SECRET=...

🔍 Troubleshooting​

Environment Issues​

# Check environment status
./env-manager.sh status

# Reset environment
./env-manager.sh clean
./env-manager.sh dev  # or prod

Database Issues​

# Development: Reset SQLite
rm database/app.db
npm run flask:dev

# Production: Check Supabase connection
python -c "import psycopg2; psycopg2.connect(os.environ['DATABASE_URL'])"

Build Issues​

# Clear caches
rm -rf node_modules/.vite
npm run build:dev  # or build

📊 Environment Features Comparison​

FeatureDevelopmentProduction
DatabaseSQLite (fast)Supabase PostgreSQL
Frontend BuildUnminified + sourcemapsOptimized + minified
APILocal Flask serverVercel serverless
DebuggingFull debug logsWarning+ logs
EmailConsole loggingSMTP sending
CORSLocalhost onlyConfigured origins
Hot Reload✅ Enabled❌ Disabled
Caching❌ Disabled✅ Enabled

🔐 Security Notes​

Development​

  • Uses development secrets (safe for local)
  • CORS allows localhost
  • Debug mode exposes error details
  • SQLite is not secure for production

Production​

  • Requires strong, unique secrets
  • CORS restricted to your domain
  • Debug mode disabled
  • Database connection secured
  • Environment variables encrypted

🎯 Best Practices​

  1. Never commit secrets - Use environment variables
  2. Test production locally - Use ./prod.sh before deploying
  3. Use different databases - Dev and prod should be separate
  4. Environment-specific configs - Don't mix dev/prod settings
  5. Regular backups - Backup production database
  6. Monitor logs - Check Vercel function logs

📞 Support​

  • Environment Issues: Run ./env-manager.sh status
  • Build Issues: Check Vercel deployment logs
  • Database Issues: Verify connection strings
  • API Issues: Check Flask logs in development