Environment Variables - Echoes of the Past

This page documents all environment variables required to run Echoes of the Past. Variables are categorized by service and importance.

Overview

Echoes of the Past uses environment variables for:

API authentication and configuration
Database connections
Third-party service integration
Feature flags and runtime configuration

Security Notice: Never commit .env files to version control. Use .env.local for local development and Vercel’s environment variable system for production.

Required Variables

These variables are mandatory for the application to function. Missing any of these will cause runtime or build errors.

Supabase (Database & Authentication)

`NEXT_PUBLIC_SUPABASE_URL`

Type: Public
Required: Yes
Used in:

next.config.ts:3
utils/supabase/server.ts:8
utils/supabase/middleware.ts:17
utils/supabase/client.ts:4

Description: Your Supabase project URL. Used for database connections and authentication. Example:

NEXT_PUBLIC_SUPABASE_URL=https://fmknwbbacrndtinyyhiw.supabase.co

How to get:

Go to your Supabase Dashboard
Select your project
Navigate to Settings → API
Copy the “Project URL”

This variable is prefixed with NEXT_PUBLIC_ so it’s accessible in the browser. The URL in next.config.ts:12 is used to configure Next.js image optimization for Supabase Storage.

`NEXT_PUBLIC_SUPABASE_ANON_KEY`

Type: Public
Required: Yes
Used in:

utils/supabase/server.ts:8
utils/supabase/middleware.ts:17
utils/supabase/client.ts:4
utils/supabase/check-env-vars.ts:4

Description: Supabase anonymous (public) API key. Safe to expose in the browser as it’s protected by Row Level Security (RLS). Example:

NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

How to get:

Go to your Supabase Dashboard
Navigate to Settings → API
Copy the “anon public” key

Vapi AI (Voice Conversations)

`NEXT_PUBLIC_VAPI_WEB_TOKEN`

Type: Public
Required: Yes
Used in:

lib/vapi.ts:3
lib/vapi.ts:7

Description: Vapi AI web token for real-time voice conversations with historical figures. Required for the core voice interaction feature. Example:

NEXT_PUBLIC_VAPI_WEB_TOKEN=sk_live_abc123def456...

How to get:

Sign up at Vapi AI
Create a new application
Navigate to API Keys
Copy your Web Token

Validation: The application throws an error at lib/vapi.ts:3 if this is not set:

if (!process.env.NEXT_PUBLIC_VAPI_WEB_TOKEN) {
  throw new Error('NEXT_PUBLIC_VAPI_WEB_TOKEN environment variable is required')
}

OpenAI (AI Generation)

`OPENAI_API_KEY`

Type: Secret
Required: Yes
Used in:

lib/ai.ts:3
lib/ai.ts:8

Description: OpenAI API key for AI-powered features including quiz generation and conversation intelligence. Example:

OPENAI_API_KEY=sk-proj-abc123...

How to get:

Go to OpenAI Platform
Navigate to API Keys
Click “Create new secret key”
Copy and store securely

Validation: Build fails at lib/ai.ts:3 if not set:

if (!process.env.OPENAI_API_KEY) {
  throw new Error('OPENAI_API_KEY is not set')
}

Security: This is a server-side only variable. Never expose this in client-side code or commit to version control.

ElevenLabs (Voice Synthesis)

`ELEVEN_LABS_API_KEY`

Type: Secret
Required: Yes
Used in:

lib/elevenlabs.ts:4

Description: ElevenLabs API key for high-quality voice synthesis and cloning of historical figure voices. Example:

ELEVEN_LABS_API_KEY=sk_abc123def456...

How to get:

Sign up at ElevenLabs
Navigate to Profile → API Keys
Generate a new API key
Copy and store securely

ElevenLabs is used in conjunction with Vapi AI (see features/call/hooks/useVapi.ts:47-55) to provide voice synthesis with specific voice IDs for each historical figure.

Upstash Redis (Rate Limiting & Caching)

`UPSTASH_REDIS_REST_URL`

Type: Secret
Required: Yes
Used in:

lib/redis.ts:3
lib/redis.ts:8

Description: REST API URL for your Upstash Redis instance, used for rate limiting and caching. Example:

UPSTASH_REDIS_REST_URL=https://us1-merry-lion-12345.upstash.io

`UPSTASH_REDIS_REST_TOKEN`

Type: Secret
Required: Yes
Used in:

lib/redis.ts:3
lib/redis.ts:9

Description: Authentication token for Upstash Redis REST API. Example:

UPSTASH_REDIS_REST_TOKEN=AabcAAIjcDE1234567890...

How to get both:

Sign up at Upstash
Create a new Redis database
Navigate to Details tab
Copy “UPSTASH_REDIS_REST_URL” and “UPSTASH_REDIS_REST_TOKEN”

Validation: Application throws error at lib/redis.ts:3 if either is missing:

if (!process.env.UPSTASH_REDIS_REST_URL || !process.env.UPSTASH_REDIS_REST_TOKEN) {
  throw new Error('UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN must be set')
}

Optional Variables

These variables enhance functionality but are not strictly required for the application to run.

Application Configuration

`NEXT_PUBLIC_APP_URL`

Type: Public
Required: Recommended
Used in:

features/auth/components/sign-in-google-btn.tsx:21

Description: The full URL of your application. Used for OAuth callbacks and redirects. Default: Derived from VERCEL_URL or defaults to http://localhost:3000 Example:

# Development
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Production
NEXT_PUBLIC_APP_URL=https://echoes-of-the-past.vercel.app

Usage: Critical for Google OAuth callback (see features/auth/components/sign-in-google-btn.tsx:21):

redirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`

If not set, OAuth authentication may fail due to incorrect callback URLs. Always set this in production.

`NEXT_PUBLIC_SERVER_URL`

Type: Public
Required: Optional
Used in:

features/call/hooks/useVapi.ts:57

Description: Webhook URL for Vapi AI callbacks. If not set, falls back to a default ngrok URL (development only). Example:

NEXT_PUBLIC_SERVER_URL=https://your-domain.com/api/webhook

Default: https://08ae-202-43-120-244.ngrok-free.app/api/webhook (hardcoded fallback) When to set:

In production for custom webhook handling
When implementing server-side conversation logging
For advanced Vapi AI integrations

`VERCEL_URL`

Type: System (Auto-set by Vercel)
Required: No
Used in:

config/metadata.ts:5

Description: Automatically provided by Vercel. Contains the deployment URL without protocol. Example:

VERCEL_URL=echoes-of-the-past-git-main-username.vercel.app

Usage: Used to construct the default URL in config/metadata.ts:5:

export const defaultUrl = process.env.VERCEL_URL 
  ? `https://${process.env.VERCEL_URL}` 
  : 'http://localhost:3000'

You don’t need to set this manually. Vercel automatically provides it for all deployments.

`NODE_ENV`

Type: System
Required: No (Auto-set)
Used in:

app/layout.tsx:43
app/(other)/auth/callback/route.ts:19

Description: Indicates the current environment. Automatically set by Node.js and build systems. Values:

development - Local development
production - Production builds
test - Test environments

Usage Examples: Conditional analytics loading (app/layout.tsx:43):

{process.env.NODE_ENV === 'production' && (
  <Script 
    defer 
    src="https://cloud.umami.is/script.js" 
    data-website-id="e2be9698-2b5e-432b-b846-a02a0a9b7733" 
  />
)}

Environment-aware redirects (app/(other)/auth/callback/route.ts:19):

const isLocalEnv = process.env.NODE_ENV === 'development'

Environment Setup Guide

Local Development

Create .env.local file

Create a .env.local file in the root directory:

touch .env.local

Add required variables

Copy this template and fill in your values:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# Vapi AI
NEXT_PUBLIC_VAPI_WEB_TOKEN=your-vapi-token

# OpenAI
OPENAI_API_KEY=sk-proj-your-key

# ElevenLabs
ELEVEN_LABS_API_KEY=your-elevenlabs-key

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

# Application (Optional)
NEXT_PUBLIC_APP_URL=http://localhost:3000

Verify setup

Start the development server:

npm run dev

Check for any environment variable errors in the console.

Production (Vercel)

Navigate to project settings

Open your Vercel dashboard
Select your project
Go to Settings → Environment Variables

Add all required variables

For each variable:

Enter the variable name
Enter the value
Select environments (Production, Preview, Development)
Click “Save”

Add optional variables

Add optional variables for enhanced functionality:

NEXT_PUBLIC_APP_URL (Use your production domain)
NEXT_PUBLIC_SERVER_URL (If using custom webhooks)

Redeploy

Trigger a new deployment to apply the changes:

git commit --allow-empty -m "Update environment variables"
git push

Or use the Vercel dashboard to redeploy.

Security Best Practices

Do’s

Store all secrets in Vercel’s encrypted environment variable system
Use different API keys for development and production
Rotate API keys regularly
Use NEXT_PUBLIC_ prefix only for truly public variables
Set appropriate environment scopes (Production vs Preview)
Monitor API usage and set rate limits

Don’ts

Never commit .env files to Git
Never expose server-side secrets in client components
Don’t use production keys in development
Don’t share API keys in screenshots or documentation
Don’t hardcode sensitive values in source code

Checking for Exposed Secrets

Before committing, verify no secrets are exposed:

# Check for .env files in git
git ls-files | grep .env

# Should return empty. If not, add to .gitignore

Ensure .gitignore includes:

.env
.env.local
.env.*.local

Variable Validation

The application validates critical environment variables at startup:

Build-time Validation

File: next.config.ts:3-5

if (!process.env.NEXT_PUBLIC_SUPABASE_URL) {
  throw new Error('NEXT_PUBLIC_SUPABASE_URL is not set')
}

Runtime Validation

Multiple services validate their required variables:

Vapi: lib/vapi.ts:3-5
OpenAI: lib/ai.ts:3-5
Redis: lib/redis.ts:3-5

Manual Validation

Check environment variable availability: File: utils/supabase/check-env-vars.ts:4

export const hasEnvVars = 
  process.env.NEXT_PUBLIC_SUPABASE_URL && 
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY

Troubleshooting

Variable Not Loaded

Problem: Environment variable returns undefined Solutions:

Restart development server after adding new variables
Verify variable name spelling (case-sensitive)
Check if variable is in correct .env.local file
For NEXT_PUBLIC_* variables, ensure they’re set at build time

Build Failures

Error: “Environment variable is not set” Solution:

Check which variable is missing from error message
Add the variable to Vercel environment settings
Redeploy the application

OAuth Callback Errors

Problem: Authentication redirects fail Solution:

Verify NEXT_PUBLIC_APP_URL matches your actual domain
Update Google OAuth callback URL to https://yourdomain.com/auth/callback
Add callback URL to Supabase redirect allowlist

API Rate Limiting

Problem: Too many API requests Solution:

Verify Redis is properly configured
Check UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN
Monitor Redis usage in Upstash dashboard

Quick Reference

Minimum Required Variables

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
NEXT_PUBLIC_VAPI_WEB_TOKEN=
OPENAI_API_KEY=
ELEVEN_LABS_API_KEY=
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

Production Variables

Add these for production:

NEXT_PUBLIC_APP_URL=https://your-domain.com
NEXT_PUBLIC_SERVER_URL=https://your-domain.com/api/webhook

Variable Prefix Guide

NEXT_PUBLIC_* - Exposed to browser, safe for client-side code
No prefix - Server-side only, never exposed to client
VERCEL_* - Automatically set by Vercel platform
NODE_ENV - Automatically set by runtime environment

Setup

Core Concepts

Deployment

​Overview

​Required Variables

​Supabase (Database & Authentication)

​NEXT_PUBLIC_SUPABASE_URL

​NEXT_PUBLIC_SUPABASE_ANON_KEY

​Vapi AI (Voice Conversations)

​NEXT_PUBLIC_VAPI_WEB_TOKEN

​OpenAI (AI Generation)

​OPENAI_API_KEY

​ElevenLabs (Voice Synthesis)

​ELEVEN_LABS_API_KEY

​Upstash Redis (Rate Limiting & Caching)

​UPSTASH_REDIS_REST_URL

​UPSTASH_REDIS_REST_TOKEN

​Optional Variables

​Application Configuration

​NEXT_PUBLIC_APP_URL

​NEXT_PUBLIC_SERVER_URL

​VERCEL_URL

​NODE_ENV

​Environment Setup Guide

​Local Development

​Production (Vercel)

​Security Best Practices

​Do’s

​Don’ts

​Checking for Exposed Secrets

​Variable Validation

​Build-time Validation

​Runtime Validation

​Manual Validation

​Troubleshooting

​Variable Not Loaded

​Build Failures

​OAuth Callback Errors

​API Rate Limiting

​Quick Reference

​Minimum Required Variables

​Production Variables

​Variable Prefix Guide

Build docs developers (and LLMs) love

Overview

Required Variables

Supabase (Database & Authentication)

`NEXT_PUBLIC_SUPABASE_URL`

`NEXT_PUBLIC_SUPABASE_ANON_KEY`

Vapi AI (Voice Conversations)

`NEXT_PUBLIC_VAPI_WEB_TOKEN`

OpenAI (AI Generation)

`OPENAI_API_KEY`

ElevenLabs (Voice Synthesis)

`ELEVEN_LABS_API_KEY`

Upstash Redis (Rate Limiting & Caching)

`UPSTASH_REDIS_REST_URL`

`UPSTASH_REDIS_REST_TOKEN`

Optional Variables

Application Configuration

`NEXT_PUBLIC_APP_URL`

`NEXT_PUBLIC_SERVER_URL`

`VERCEL_URL`

`NODE_ENV`

Environment Setup Guide

Local Development

Production (Vercel)

Security Best Practices

Do’s

Don’ts

Checking for Exposed Secrets

Variable Validation

Build-time Validation

Runtime Validation

Manual Validation

Troubleshooting

Variable Not Loaded

Build Failures

OAuth Callback Errors

API Rate Limiting

Quick Reference

Minimum Required Variables

Production Variables

Variable Prefix Guide