Guido.Tech/ENVIRONMENT_CONFIG.md

Environment Configuration Guide

Overview

The HPC Simulation system automatically adapts between development and production environments based on the ENVIRONMENT variable.

Configuration Files

Development (Local)

• File: .env (in project root)
• ENVIRONMENT=development
• Uses localhost URLs

Production (Render.com)

• Set environment variables in Render dashboard
• ENVIRONMENT=production
• PRODUCTION_URL=https://your-app.onrender.com
• Automatically adapts all URLs

Key Environment Variables

Required for Both Environments

Variable	Description	Example
GEMINI_API_KEY	Google Gemini API key	AIzaSy...
ENVIRONMENT	Environment mode	development or production

Production-Specific

Variable	Description	Example
PRODUCTION_URL	Your Render.com app URL	https://hpc-ai.onrender.com

Optional

Variable	Default	Description
ELEVENLABS_API_KEY	-	Voice synthesis (optional)
GEMINI_MODEL	gemini-1.5-pro	AI model version
STRATEGY_COUNT	3	Strategies per lap
FAST_MODE	true	Use shorter prompts

How It Works

URL Auto-Configuration

The config.py automatically provides environment-aware URLs:

settings = get_settings()

# Automatically returns correct URL based on environment:
settings.base_url          # http://localhost:9000 OR https://your-app.onrender.com
settings.websocket_url     # ws://localhost:9000 OR wss://your-app.onrender.com
settings.internal_enrichment_url  # Always http://localhost:8000 (internal)

Development Environment

ENVIRONMENT=development
# Result:
# - base_url: http://localhost:9000
# - websocket_url: ws://localhost:9000
# - Dashboard connects to: ws://localhost:9000/ws/dashboard

Production Environment

ENVIRONMENT=production
PRODUCTION_URL=https://hpc-ai.onrender.com
# Result:
# - base_url: https://hpc-ai.onrender.com
# - websocket_url: wss://hpc-ai.onrender.com
# - Dashboard connects to: wss://hpc-ai.onrender.com/ws/dashboard

Component-Specific Configuration

1. AI Intelligence Layer

Development:

• Binds to: 0.0.0.0:9000
• Enrichment client connects to: http://localhost:8000
• Dashboard WebSocket: ws://localhost:9000/ws/dashboard

Production:

• Binds to: 0.0.0.0:9000 (Render exposes externally)
• Enrichment client connects to: http://localhost:8000 (internal)
• Dashboard WebSocket: wss://your-app.onrender.com/ws/dashboard

2. Enrichment Service

Development:

• Binds to: 0.0.0.0:8000
• Accessed at: http://localhost:8000

Production:

• Binds to: 0.0.0.0:8000 (internal only)
• Accessed internally at: http://localhost:8000
• Not exposed externally (behind AI layer)

3. Dashboard (Frontend)

Auto-detects environment:

// Automatically uses current host and protocol
const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
const host = window.location.host;
const wsUrl = `${protocol}//${host}/ws/dashboard`;

4. Pi Simulator (Client)

Development:

python simulate_pi_websocket.py \
  --ws-url ws://localhost:9000/ws/pi \
  --enrichment-url http://localhost:8000

Production:

python simulate_pi_websocket.py \
  --ws-url wss://your-app.onrender.com/ws/pi \
  --enrichment-url https://your-app.onrender.com  # If exposed

Quick Setup

Local Development

1. Create .env in project root:

GEMINI_API_KEY=your_key_here
ENVIRONMENT=development

2. Start services:

./start.sh

Render.com Production

1. Set environment variables in Render dashboard:

GEMINI_API_KEY=your_key_here
ENVIRONMENT=production
PRODUCTION_URL=https://your-app-name.onrender.com

2. Deploy - URLs auto-configure!

Troubleshooting

Issue: WebSocket connection fails in production

Check:

1. ENVIRONMENT=production is set
2. PRODUCTION_URL matches your actual Render URL (including https://)
3. Dashboard uses wss:// protocol (should auto-detect)

Issue: Enrichment service unreachable

In production:

• Both services run in same container
• Internal communication uses http://localhost:8000
• This is automatic, no configuration needed

In development:

• Ensure enrichment service is running: python scripts/serve.py
• Check http://localhost:8000/health

Issue: Pi simulator can't connect

Development:

# Test connection
curl http://localhost:9000/health
wscat -c ws://localhost:9000/ws/pi

Production:

# Test connection
curl https://your-app.onrender.com/health
wscat -c wss://your-app.onrender.com/ws/pi

Environment Variable Priority

1. Render Environment Variables (highest priority in production)
2. .env file (development)
3. Default values (in config.py)

Best Practices

Development

• ✅ Use .env file
• ✅ Keep ENVIRONMENT=development
• ✅ Use localhost URLs
• ❌ Don't commit .env to git

Production

• ✅ Set all variables in Render dashboard
• ✅ Use ENVIRONMENT=production
• ✅ Set PRODUCTION_URL after deployment
• ✅ Use HTTPS/WSS protocols
• ❌ Don't hardcode URLs in code

Example Configurations

.env (Development)

GEMINI_API_KEY=AIzaSyDK_jxVlJUpzyxuiGcopSFkiqMAUD3-w0I
GEMINI_MODEL=gemini-2.5-flash
ENVIRONMENT=development
ELEVENLABS_API_KEY=your_key_here
STRATEGY_COUNT=3
FAST_MODE=true

Render Environment Variables (Production)

GEMINI_API_KEY=AIzaSyDK_jxVlJUpzyxuiGcopSFkiqMAUD3-w0I
GEMINI_MODEL=gemini-2.5-flash
ENVIRONMENT=production
PRODUCTION_URL=https://hpc-simulation-ai.onrender.com
ELEVENLABS_API_KEY=your_key_here
STRATEGY_COUNT=3
FAST_MODE=true

Migration Checklist

When deploying to production:

• Set ENVIRONMENT=production in Render
• Deploy and get Render URL
• Set PRODUCTION_URL with your Render URL
• Test health endpoint: https://your-app.onrender.com/health
• Test WebSocket: wss://your-app.onrender.com/ws/pi
• Open dashboard: https://your-app.onrender.com/dashboard
• Verify logs show production URLs

Done! The system will automatically use production URLs for all connections.