Skip to main content

Environment Configuration Guide

This document explains how environment variables are configured for development and production environments.

Overview​

The project uses environment-specific configuration files to ensure development and production use different ports and settings without affecting each other.

Port Configuration​

Development​

  • Backend: Port 33001
  • Frontend: Port 33000
  • Database: Port 5432 (PostgreSQL in Docker)

Production​

  • Backend: Port 3001 (or behind reverse proxy)
  • Frontend: Standard production deployment
  • Database: Production PostgreSQL instance

Backend Configuration​

File Structure​

stemblockai-backend/
├── .env                    # Base configuration (production defaults)
├── .env.development        # Development overrides
└── .env.example           # Template file

.env (Production Defaults)​

Contains production-safe defaults:

PORT=3001
NODE_ENV="production"
FRONTEND_URL="http://localhost:3000"
DATABASE_URL="postgresql://..."

.env.development (Development Overrides)​

Overrides specific values for local development:

# Development-only overrides
PORT=33001
FRONTEND_URL="http://localhost:33000"

How It Works​

The main.ts file loads environment variables in this order:

  1. Loads .env (base configuration)
  2. Loads .env.development with override: true (when NODE_ENV=development)
// src/main.ts
const nodeEnv = process.env.NODE_ENV || 'development';
config({ path: resolve(process.cwd(), '.env') });
config({ path: resolve(process.cwd(), `.env.${nodeEnv}`), override: true });

This ensures:

  • ✅ Development uses port 33001
  • ✅ Production uses port 3001
  • ✅ No production config is modified

Frontend Configuration​

File Structure​

stemblockai-frontend/
├── .env.local             # Local overrides (git-ignored)
├── .env.development       # Development environment (auto-loaded by Next.js)
├── .env.production        # Production environment (auto-loaded by Next.js)
└── .env.local.example     # Template file

.env.development​

# Backend API URL (Development port)
NEXT_PUBLIC_API_URL=http://localhost:33001

.env.production​

# Backend API URL (Production)
NEXT_PUBLIC_API_URL=https://stemblockai-backend-gvt9i.ondigitalocean.app

.env.local​

Local overrides (optional, git-ignored):

# This file is for local-only overrides
# .env.development and .env.production take precedence
NEXT_PUBLIC_API_URL=http://localhost:3001

How It Works​

Next.js automatically loads the correct environment file based on the command:

  • npm run dev → Loads .env.development
  • npm run build → Loads .env.production
  • .env.local can override both (but is git-ignored)

Package.json Scripts​

Frontend scripts are configured for the correct ports:

{
  "scripts": {
    "dev": "next dev -p 33000",
    "start": "next start -p 33000"
  }
}

Deployment Checklist​

Development​

  1. ✅ Backend runs on port 33001
  2. ✅ Frontend runs on port 33000
  3. ✅ All .env.development files are in place

Production​

  1. ✅ Backend uses .env (port 3001)
  2. ✅ Frontend uses .env.production
  3. ✅ No .env.development files are deployed
  4. ✅ Sensitive values (JWT_SECRET, etc.) are overridden via deployment environment variables

Testing Configuration​

To verify the correct ports are being used:

Backend​

cd stemblockai-backend
npm run start:dev

# Should see: "Application is running on: http://localhost:33001"
curl http://localhost:33001/health
# Should return: {"status":"ok","database":"connected"}

Frontend​

cd stemblockai-frontend
npm run dev

# Should see: "- Local: http://localhost:33000"

Troubleshooting​

Port Already in Use​

If you see EADDRINUSE error:

# Find process using the port
lsof -i :33001

# Kill the process
kill -9 <PID>

Wrong Port Being Used​

  1. Check NODE_ENV is set correctly (defaults to "development")
  2. Verify .env.development file exists
  3. Check for typos in environment variable names
  4. Restart the development server

Production Deployment Issues​

  1. Ensure .env.development is NOT deployed
  2. Verify production environment variables override file-based config
  3. Check deployment platform env variable precedence

Additional Environment Variables​

The following environment variables are required for full functionality but not covered in the port configuration above:

Google Cloud / Vertex AI​

GOOGLE_CLOUD_PROJECT="stemblock-ai-prod"
GOOGLE_CLOUD_LOCATION="us-central1"
GCP_SERVICE_ACCOUNT_KEY_BASE64="<base64-encoded service account JSON>"
VERTEX_FLASH_MODEL="gemini-2.0-flash"
VERTEX_PRO_MODEL="gemini-2.0-pro"
VERTEX_LITE_MODEL="gemini-2.0-flash-lite"

Stripe (Billing)​

STRIPE_SECRET_KEY="sk_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
STRIPE_PUBLISHABLE_KEY="pk_..."

Database (Neon — dual connections)​

DATABASE_URL="postgresql://user:pass@ep-xyz-pooler.us-east-2.aws.neon.tech/stemblock_db?sslmode=require"
DIRECT_DATABASE_URL="postgresql://user:pass@ep-xyz.us-east-2.aws.neon.tech/stemblock_db?sslmode=require"

See infrastructure/NEON_MIGRATION_GUIDE.md for details on pooled vs. direct connections.

Security Notes​

  • ✅ .env.local is git-ignored (contains sensitive local config)
  • ✅ .env.development is committed (safe dev config only)
  • ✅ .env.production is committed (references production URLs, no secrets)
  • ✅ .env contains development values (safe to commit)
  • ⚠️ Sensitive values (API keys, secrets) should be set via deployment platform

Summary​

This configuration ensures:

  • Development and production environments are completely isolated
  • No production configuration is accidentally modified during development
  • Port conflicts are avoided
  • Easy to switch between environments
  • Production deployments remain unchanged

Last Updated: 2025-12-13 Maintained By: StemBlock AI Team