Skip to main content

Development Setup Guide

Complete guide for setting up and managing your local development environment.

Table of Contents​

Environment Architecture​

Development Environment​

  • Frontend: Vite dev server with hot reloading
  • Backend: Flask with debug mode
  • Database: Supabase PostgreSQL
  • 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

Initial Setup​

1. Install Prerequisites​

# Node.js 18+ (check version)
node --version

# Python 3.13+ (check version)
python --version

# Git (check version)
git --version

2. Clone Repository​

git clone <your-repo-url>
cd "AI Agentification Platform Website Content"

3. Install Dependencies​

Frontend Dependencies​

npm install

Backend Dependencies​

# Create virtual environment (recommended)
python -m venv venv

# Activate virtual environment
source venv/bin/activate  # Mac/Linux
# OR
venv\Scripts\activate     # Windows

# Install Python packages
pip install -r requirements.txt

Environment Variables​

Development Environment Variables​

Create a .env file in the project root:

# ========================================
# ENVIRONMENT
# ========================================
NODE_ENV=development
FLASK_ENV=development

# ========================================
# SUPABASE CONFIGURATION
# ========================================
# Project URL (from Supabase Dashboard → Settings → API)
VITE_SUPABASE_URL=https://your-project.supabase.co

# Anon/Public Key (safe for frontend)
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Service Role Key (BACKEND ONLY - never expose to frontend)
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Database URL (optional - uses Supabase by default)
DATABASE_URL=postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:5432/postgres

# ========================================
# FLASK CONFIGURATION
# ========================================
SECRET_KEY=dev-secret-key-change-in-production
JWT_SECRET=dev-jwt-secret-key-change-in-production

# ========================================
# DEVELOPMENT FEATURES
# ========================================
DEBUG=true
CORS_ORIGINS=http://localhost:5173,http://localhost:5001

# ========================================
# EMAIL (Optional - for development)
# ========================================
EMAIL_ENABLED=false  # Set to true to test email sending
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password

# ========================================
# EXTERNAL SERVICES (Optional)
# ========================================
# YouTube API (for video metadata)
VITE_YOUTUBE_API_KEY=your_youtube_api_key

# Cloudinary (for media uploads)
VITE_CLOUDINARY_CLOUD_NAME=your_cloud_name
VITE_CLOUDINARY_UPLOAD_PRESET=your_upload_preset

# Google Analytics
VITE_GA4_MEASUREMENT_ID=G-XXXXXXXXXX

Where to Find These Values​

Supabase Credentials​

  1. Go to supabase.com/dashboard
  2. Select your project
  3. Navigate to Settings → API
  4. Copy:
    • Project URL → VITE_SUPABASE_URL
    • anon public key → VITE_SUPABASE_ANON_KEY
    • service_role key → SUPABASE_SERVICE_ROLE_KEY

Database URL​

  1. In Supabase Dashboard, go to Settings → Database
  2. Copy the Connection String (URI format)
  3. Replace [YOUR-PASSWORD] with your database password

YouTube API Key (Optional)​

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Enable YouTube Data API v3
  4. Create credentials → API Key

Cloudinary (Optional)​

  1. Go to cloudinary.com
  2. Sign up for free account
  3. Get Cloud Name and Upload Preset from dashboard

Environment Security​

Files to NEVER Commit​

# These files are in .gitignore
.env                    # Active environment config
.env.local             # Local overrides
.env.*.local           # Environment-specific overrides
venv/                  # Python virtual environment
node_modules/          # Node dependencies

Safe Template Files (OK to Commit)​

.env.example           # Template showing required variables
.env.development.example   # Development template
.env.production.example    # Production template

Setting Up Templates​

Create safe template files:

# Copy your .env and remove sensitive values
cp .env .env.example

# Edit .env.example and replace actual values with placeholders
# Example:
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_anon_key_here
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here

Development Workflow​

Daily Development​

Start the development servers:

# Start both frontend and backend (recommended)
npm run dev

# OR start individually:
npm run dev:frontend   # Frontend only (port 5173)
npm run dev:backend    # Backend only (port 5001)

The application will be available at:

Hot Reloading​

  • Frontend: Changes to .jsx, .css, .js files reload instantly
  • Backend: Changes to .py files restart the Flask server automatically
  • Database: Schema changes require running new migrations

Development Tools​

Browser DevTools​

  • React DevTools: Install browser extension for React debugging
  • Console: Check for errors and API responses
  • Network: Monitor API calls to backend

Backend Debugging​

# Run Flask with debug mode (already enabled in development)
DEBUG=true python main.py

# Check backend logs in terminal
# All API requests and responses are logged

Database Tools​

  • Supabase Dashboard: View and edit database tables
  • SQL Editor: Run queries and test migrations
  • API Logs: Monitor Supabase API usage

Database Management​

Running Migrations​

Initial Setup​

# Run all migrations in Supabase Dashboard
# Go to SQL Editor → New Query
# Copy and run each file from supabase/migrations/

Creating New Migrations​

  1. Create a new file in supabase/migrations/
# Naming convention: YYYYMMDD_description.sql
# Example: 20250103_add_user_roles.sql
  1. Write your migration SQL:
-- Add a new column
ALTER TABLE users ADD COLUMN role TEXT DEFAULT 'user';

-- Create an index
CREATE INDEX idx_users_role ON users(role);

-- Update existing data
UPDATE users SET role = 'admin' WHERE email = 'admin@example.com';
  1. Run in Supabase SQL Editor
  2. Test thoroughly in development
  3. Document in migration file comments

Database Best Practices​

  • Always use migrations - Never manually edit production tables
  • Test locally first - Use development database for testing
  • Backup before changes - Supabase has automatic backups
  • Use transactions - Wrap related changes in transactions
  • Document changes - Add comments to migration files

Security Best Practices​

Environment Variables​

Development​

# Safe for development (not production)
SECRET_KEY=dev-secret-key-change-in-production
JWT_SECRET=dev-jwt-secret-key-change-in-production
DEBUG=true

Production​

# Generate strong random keys for production
SECRET_KEY=$(openssl rand -hex 32)
JWT_SECRET=$(openssl rand -hex 32)
DEBUG=false

API Security​

  • Service Role Key: Only use in backend, NEVER in frontend
  • Anon Key: Safe for frontend, limited permissions
  • JWT Tokens: Validate on backend before database operations
  • CORS: Configure allowed origins properly

Row Level Security (RLS)​

Supabase uses RLS policies to secure database access:

-- Example: Users can only see their own enrollments
CREATE POLICY "Users can view own enrollments"
ON course_enrollments FOR SELECT
USING (auth.uid() = user_id);

-- Example: Only admins can insert content
CREATE POLICY "Admins can insert content"
ON content FOR INSERT
WITH CHECK (
  auth.uid() IN (
    SELECT id FROM auth.users
    WHERE raw_user_meta_data->>'role' = 'admin'
  )
);

Secret Rotation​

If secrets are compromised:

  1. Generate new keys in Supabase Dashboard
  2. Update environment variables in all environments
  3. Redeploy applications with new keys
  4. Invalidate old sessions (users will need to re-login)

Troubleshooting​

Common Issues​

"Failed to fetch" API Errors​

# Check if backend is running
curl http://localhost:5001/api/health

# Restart backend
npm run dev:backend

"Invalid API credentials" Errors​

# Verify environment variables are loaded
node -e "console.log(process.env.VITE_SUPABASE_URL)"

# Check .env file exists and has correct values
cat .env | grep SUPABASE_URL

Database Connection Errors​

# Test database connection
psql $DATABASE_URL

# Check if Supabase project is active
# Go to Supabase Dashboard → Settings → General

Port Already in Use​

# Find process using port 5173
lsof -i :5173

# Kill the process
kill -9 <PID>

# Or use different port
PORT=3000 npm run dev:frontend

Development Server Issues​

Frontend Won't Start​

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clear Vite cache
rm -rf node_modules/.vite
npm run dev

Backend Won't Start​

# Check Python version
python --version  # Should be 3.13+

# Reinstall Python dependencies
pip install --force-reinstall -r requirements.txt

# Check for syntax errors
python -m py_compile main.py

Database Issues​

Tables Not Found​

# Run migrations in Supabase SQL Editor
# Check Table Editor to verify tables exist
# Ensure RLS policies don't block access

RLS Policy Blocking Queries​

-- Temporarily disable RLS for testing (DEVELOPMENT ONLY)
ALTER TABLE table_name DISABLE ROW LEVEL SECURITY;

-- Re-enable after testing
ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;

Environment Comparison​

FeatureDevelopmentProduction
Frontend BuildUnminified + sourcemapsOptimized + minified
BackendFlask dev serverVercel serverless
DatabaseSupabase (dev project)Supabase (prod project)
Debug LogsFull verbose loggingWarning+ only
EmailConsole/disabledSMTP enabled
CORSLocalhost onlyConfigured domains
Hot ReloadEnabledDisabled
Error MessagesFull stack tracesSanitized messages
CachingDisabledEnabled (CDN)

Next Steps​

Additional Resources​