Deployment
Environment Variables

Environment Variables

Complete reference for all environment variables in HiveForge.

Quick Reference

Copy .env.example to .env and configure:

cp .env.example .env

Application URLs

# Frontend URL
NEXT_PUBLIC_APP_URL=http://localhost:3000
 
# Backend API URL
NEXT_PUBLIC_API_URL=http://localhost:8000

Supabase

# Supabase Project URL
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
 
# Supabase Anonymous Key (public)
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 
# Supabase Service Role Key (secret - server-side only)
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
 
# JWT Secret (for token verification)
SUPABASE_JWT_SECRET=your-jwt-secret

Where to find:

  1. Go to Supabase Dashboard
  2. Select your project
  3. Go to Settings > API
  4. Copy URL and keys

Stripe

# Stripe Publishable Key (public)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
 
# Stripe Secret Key (secret)
STRIPE_SECRET_KEY=sk_test_...
 
# Stripe Webhook Secret
STRIPE_WEBHOOK_SECRET=whsec_...
 
# Product Price IDs
STRIPE_PRICE_ID_FREE=price_...
STRIPE_PRICE_ID_PRO=price_...
STRIPE_PRICE_ID_ENTERPRISE=price_...

Where to find:

  1. Stripe Dashboard > Developers > API keys
  2. For webhook secret: Developers > Webhooks > Add endpoint

Email (Resend)

# Resend API Key
RESEND_API_KEY=re_...
 
# From Email Address
RESEND_FROM_EMAIL=noreply@yourdomain.com

Where to find:

  1. Resend Dashboard > API Keys
  2. Create new API key

AI Services

# OpenAI
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4
 
# Anthropic Claude
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-3-opus-20240229

Where to find:

Platform Configuration

# Platform Admin Emails (comma-separated)
PLATFORM_ADMIN_EMAILS=admin@example.com,admin2@example.com
 
# Enable Hard Isolation Mode
HARD_ISOLATION_ENABLED=false
 
# App Environment
NODE_ENV=development  # development, production, test

Monitoring & Analytics

# Sentry (Error Tracking)
NEXT_PUBLIC_SENTRY_DSN=https://...@sentry.io/...
SENTRY_AUTH_TOKEN=...
SENTRY_ORG=your-org
SENTRY_PROJECT=hiveforge
 
# PostHog (Analytics - optional)
NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

Database (Optional)

If using direct PostgreSQL connection:

# Database URL
DATABASE_URL=postgresql://user:password@localhost:5432/hiveforge
 
# Connection Pool Size
DATABASE_POOL_SIZE=10

Redis (Optional)

For caching and rate limiting:

REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=your-redis-password

Security

# Session Secret (random string)
SESSION_SECRET=your-random-secret-min-32-chars
 
# CORS Origins (comma-separated)
CORS_ORIGINS=http://localhost:3000,https://yourdomain.com
 
# Rate Limit (requests per minute)
RATE_LIMIT_MAX=100

Feature Flags

# Enable specific features
ENABLE_AI_FEATURES=true
ENABLE_WEBHOOKS=true
ENABLE_CUSTOM_DOMAINS=true
ENABLE_SSO=false

Production Settings

Additional variables for production:

# Production URLs
NEXT_PUBLIC_APP_URL=https://app.yourdomain.com
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
 
# Production Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-prod-project.supabase.co
 
# Production Stripe (live keys)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_SECRET_KEY=sk_live_...
 
# Production monitoring
NODE_ENV=production
LOG_LEVEL=info

Environment-Specific Files

.env                    # Local development (gitignored)
.env.example           # Template (committed)
.env.local             # Local overrides (gitignored)
.env.production        # Production values (gitignored)
.env.test              # Test environment (gitignored)

Security Best Practices

  1. Never commit secrets: Add .env to .gitignore
  2. Use different keys per environment: Don't reuse production keys in development
  3. Rotate regularly: Change secrets periodically
  4. Minimum permissions: Use least-privilege API keys
  5. Environment variables in CI/CD: Set secrets in Netlify/Railway settings

Validation

HiveForge validates environment variables on startup:

// apps/web/src/lib/env.ts
import { z } from 'zod'
 
const envSchema = z.object({
  NEXT_PUBLIC_APP_URL: z.string().url(),
  NEXT_PUBLIC_SUPABASE_URL: z.string().url(),
  NEXT_PUBLIC_SUPABASE_ANON_KEY: z.string().min(1),
  // ... more validations
})
 
export const env = envSchema.parse(process.env)

Troubleshooting

Missing Environment Variable

Error: Environment variable SUPABASE_SERVICE_ROLE_KEY is required

Solution: Add the variable to your .env file

Invalid Format

Error: NEXT_PUBLIC_APP_URL must be a valid URL

Solution: Ensure URLs include protocol (http:// or https://)

Production vs Development

Different keys needed:

  • Development: Use test/development API keys
  • Production: Use live/production API keys

Next Steps

Deployment OverviewDeploy to Netlify