Coachable CardsDocs
Back to Platform

Environment Variables

Goal

Understand all required and optional environment variables, what breaks if they're missing, and how to set up local development.

Quick Start

  1. Copy .env.example to .env.local
  2. Fill in required variables
  3. Start dev server: npm run dev

Required for production:

  • Supabase credentials
  • AWS S3 credentials
  • Redis (Upstash for production)

Required Environment Variables

Supabase (Database)

Required for: All database operations, authentication

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

What breaks if missing:

  • ❌ Authentication fails
  • ❌ Database queries fail
  • ❌ Deck creation fails
  • ❌ User sessions don't work

Get from: Supabase Dashboard

AWS S3 (Storage)

Required for: PDF storage, image uploads, file hosting

AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_REGION=us-east-2
S3_BUCKET=your-bucket-name

What breaks if missing:

  • ❌ PDF uploads fail
  • ❌ Image uploads fail
  • ❌ File storage doesn't work
  • ❌ Deck PDFs can't be served

Get from: AWS Console → IAM → Access Keys

Redis (Caching & Rate Limiting)

Required for: Rate limiting, caching, session management

Local development:

REDIS_URL=redis://localhost:6379

Production (Upstash):

UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-upstash-token

What breaks if missing:

  • ⚠️ Rate limiting disabled (security risk in production)
  • ⚠️ Caching doesn't work (slower performance)
  • ✅ App still works, but less secure/performant

Get from: Upstash Console

Optional but Recommended

Email Service (Resend)

Required for: Email notifications, onboarding emails

RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxx
RESEND_FROM_EMAIL=Coachable Cards <noreply@c.cards>
RESEND_FROM_EMAIL_ONBOARDING=Coachable Cards <onboarding@c.cards>
RESEND_REPLY_TO=support@coachablecards.com

What breaks if missing:

  • ⚠️ Email notifications don't send
  • ⚠️ Onboarding emails fail
  • ✅ App still works, but no emails

Get from: Resend API Keys

Analytics (PostHog)

Required for: User analytics, event tracking

NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxx
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

What breaks if missing:

  • ⚠️ Analytics don't track
  • ⚠️ User events not recorded
  • ✅ App still works, but no analytics

Get from: PostHog Project Settings

Payment Processing (Stripe)

Required for: Payments, subscriptions

STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET_CREATE=whsec_xxxxxxxxxxxxxxxxxxxxx

What breaks if missing:

  • ⚠️ Payment processing fails
  • ⚠️ Subscriptions don't work
  • ✅ App still works, but no payments

Get from: Stripe Dashboard

AI Services (OpenAI)

Required for: AI features, card generation

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxx

What breaks if missing:

  • ⚠️ AI card generation fails
  • ⚠️ AI features don't work
  • ✅ App still works, but no AI features

Get from: OpenAI Platform

Local Development Quick Start

1. Copy Environment Template

cp env.example .env.local

2. Fill in Required Variables

Minimum for local dev:

# Supabase (required)
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321  # Local Supabase
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-local-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-local-service-key

# Redis (optional for local)
REDIS_URL=redis://localhost:6379

# Base URL
NEXT_PUBLIC_BASE_URL=http://localhost:3000
NEXT_PUBLIC_SITE_URL=http://localhost:3000

3. Start Local Supabase (Optional)

npx supabase start

This will give you local Supabase credentials.

4. Start Local Redis (Optional)

# Using Docker
docker run -d -p 6379:6379 redis

# Or using Homebrew
brew install redis
brew services start redis

5. Start Development Server

npm install
npm run dev

Visit http://localhost:3000

Environment Validation

The app validates environment variables on startup. Check the console for:

  • ✅ Required vars present → App works
  • ⚠️ Optional vars missing → App works with limited features
  • ❌ Required vars missing → App fails to start

Validation Function

// lib/env-validation.ts
validateEnv() // Returns validation results

Production Checklist

Before deploying to production, ensure:

  • [ ] All required variables set in Vercel/environment
  • [ ] NODE_ENV=production
  • [ ] Upstash Redis configured (not local Redis)
  • [ ] Production Supabase project configured
  • [ ] Production S3 bucket configured
  • [ ] PostHog configured (for analytics)
  • [ ] Resend configured (for emails)
  • [ ] Stripe configured (if using payments)
  • [ ] NEXT_PUBLIC_BASE_URL set to production domain
  • [ ] NEXT_PUBLIC_SITE_URL set to production domain

Common Issues

Issue: "Missing required environment variable"

Symptom: App fails to start, error in console

Cause: Required variable not set

Fix:

  1. Check .env.local exists
  2. Verify variable name is correct
  3. Restart dev server: npm run dev

Issue: "Rate limiting not working"

Symptom: No rate limits applied

Cause: Redis/Upstash not configured

Fix:

  • Local: Set REDIS_URL=redis://localhost:6379
  • Production: Set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN

Issue: "PostHog not firing"

Symptom: Analytics events not tracked

Cause: PostHog keys not set

Fix: Set NEXT_PUBLIC_POSTHOG_KEY and NEXT_PUBLIC_POSTHOG_HOST

See Troubleshooting Guide for more.

Next Steps

Environment issues? → Troubleshooting Guide