Skip to main content

​
Overview

jøsh requires several environment variables to function properly. Create a .env file in the project root and configure the following variables.
Never commit .env files to version control. All .env* files are gitignored by default.

​
Required Variables

​
Database Configuration

PostgreSQL database connection strings for Prisma. 
DATABASE_URL="postgresql://user:password@host:port/database"
DIRECT_URL="postgresql://user:password@host:port/database"
VariableDescription
DATABASE_URLPostgreSQL connection string with connection pooling support
DIRECT_URLDirect PostgreSQL connection string (without pooling) for migrations
When using services like Supabase or Neon, DATABASE_URL typically uses connection pooling (port 6543), while DIRECT_URL connects directly (port 5432).

​
AI Gateway Configuration

API key for AI service integrations (OpenAI, Mistral). 
AI_GATEWAY_API_KEY="your-api-key-here"
VariableDescriptionUsed By
AI_GATEWAY_API_KEYAPI key for AI servicesProfile structuring, onboarding, scheduling, photo tagging, ID extraction
Missing AI_GATEWAY_API_KEY will cause AI-powered features to fail, including TPO onboarding and profile generation.
Used in:
  • src/lib/tpoScheduling.ts:36
  • src/lib/tpoPhotoTags.ts:23
  • src/lib/tpoOnboardingAdlib.ts:24
  • src/lib/tpoAnswerQuality.ts:131
  • src/lib/profileStructuring.ts:346
  • src/lib/onboardingGaps.ts:39
  • src/lib/dlExtract.ts:104

​
Surge SMS Configuration

Surge API credentials for SMS messaging functionality. 
SURGE_API_KEY="your-surge-api-key"
SURGE_ACCOUNT_ID="your-surge-account-id"
SURGE_WEBHOOK_SECRET="your-webhook-secret"
VariableDescriptionRequired For
SURGE_API_KEYSurge API authentication keySending SMS messages
SURGE_ACCOUNT_IDYour Surge account identifierSMS API requests
SURGE_WEBHOOK_SECRETSecret for validating webhook signaturesWebhook security
The Surge SMS integration is used for the TPO (dating) feature to communicate with users via text message.
Used in:
  • src/lib/surgeSend.ts:5
  • src/lib/surgeWebhook.ts:3
  • src/app/api/tpo/webhook/route.ts:78

​
Supabase Configuration

Supabase credentials for file storage and authentication. 
SUPABASE_PROJECT_URL="https://your-project.supabase.co"
SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"
SUPABASE_UPLOAD_BUCKET="tpo-uploads"
VariableDescriptionDefault
SUPABASE_PROJECT_URLYour Supabase project URL-
SUPABASE_SERVICE_ROLE_KEYSupabase service role key (admin access)-
SUPABASE_UPLOAD_BUCKETBucket name for file uploadstpo-uploads
The service role key has admin privileges. Never expose it in client-side code.
Used in:
  • src/app/api/tpo/webhook/route.ts:31
  • src/app/api/tpo/admin/signed-url/route.ts:9

​
Internal API Authentication

API key for internal service authentication. 
MUTUAL_INTERNAL_API_KEY="your-internal-api-key"
VariableDescription
MUTUAL_INTERNAL_API_KEYSecret key for authenticating internal API requests
Used in:
  • src/lib/internalApiAuth.ts:4

​
Optional Variables

​
Development Environment

NODE_ENV="development"
VariableDescriptionValues
NODE_ENVApplication environment modedevelopment, production, test
Next.js automatically sets NODE_ENV during build and development. You typically don’t need to set this manually.

​
Webhook Validation (Development)

SURGE_SKIP_WEBHOOK_VALIDATION="true"
VariableDescriptionDefault
SURGE_SKIP_WEBHOOK_VALIDATIONSkip webhook signature validation (dev only)false
Only use SURGE_SKIP_WEBHOOK_VALIDATION=true in local development. Never skip validation in production.

​
Environment-Specific Configuration

​
Local Development

Example .env file for local development: 
# Database
DATABASE_URL="postgresql://postgres:password@localhost:5432/jmash"
DIRECT_URL="postgresql://postgres:password@localhost:5432/jmash"

# AI Services
AI_GATEWAY_API_KEY="sk-..."

# Surge SMS
SURGE_API_KEY="surge_..."
SURGE_ACCOUNT_ID="acc_..."
SURGE_WEBHOOK_SECRET="whsec_..."

# Supabase
SUPABASE_PROJECT_URL="https://xxxxx.supabase.co"
SUPABASE_SERVICE_ROLE_KEY="eyJ..."
SUPABASE_UPLOAD_BUCKET="tpo-uploads"

# Internal
MUTUAL_INTERNAL_API_KEY="internal_..."

# Development
SURGE_SKIP_WEBHOOK_VALIDATION="true"

​
Production (Vercel)

For production deployment on Vercel:
  1. Navigate to your project settings
  2. Go to Environment Variables
  3. Add all required variables
  4. Set appropriate values for production environments
Vercel automatically injects environment variables during build and runtime. Use the Vercel dashboard to manage production secrets.

​
Validation

The application validates required environment variables at runtime. Missing critical variables will throw errors: 
if (!process.env.AI_GATEWAY_API_KEY) {
  throw new Error("Missing AI_GATEWAY_API_KEY");
}
Check your application logs during startup to catch any missing or misconfigured environment variables.

​
Security Best Practices

1

Use different credentials for each environment

Maintain separate API keys and database credentials for development, staging, and production.
2

Rotate secrets regularly

Periodically update API keys and webhook secrets, especially after team member changes.
3

Restrict service role keys

Use Supabase RLS (Row Level Security) policies even with service role keys when possible.
4

Monitor for exposed secrets

Use tools like GitHub secret scanning to detect accidentally committed credentials.

​
Next Steps

Local Setup

Set up your local development environment

Deployment

Deploy jøsh to production

Build docs developers (and LLMs) love

Get started for freeTalk to us