Environment Setup – BetterLearn

🚀

Quick Start

Copy .env.example to .env.local and fill in your values. All variables listed here are required unless marked optional.

📋 Required Services

You'll need accounts with these services before proceeding:

🔐

Clerk

User authentication and management. clerk.com

🗄️

MongoDB Atlas

Cloud database hosting. mongodb.com/atlas

✨

Google AI Studio

Gemini API for AI features. aistudio.google.com

🤖

OpenAI

GPT models for AI Assistant. platform.openai.com

💳

Stripe

Payment processing. stripe.com

☁️

AWS S3

File storage. aws.amazon.com/s3

📄 Environment File Template

Create a .env.local file in your project root with the following variables:

.env.local

# ===================================
# BetterLearn Environment Configuration
# ===================================

# App Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000

# ===================================
# Clerk Authentication
# ===================================
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
CLERK_SECRET_KEY=sk_test_xxxxx
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/dashboard

# ===================================
# Database
# ===================================
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/betterlearn

# ===================================
# AI Services
# ===================================
# Google Gemini (Primary - Quiz Generation & Tools)
GEMINI_API_KEY=AIzaSyXXXXXXXXXXXXXXXXXXXX

# OpenAI (AI Assistant - GPT Models)
OPENAI_API_KEY=sk-proj-XXXXXXXXXXXXXXXXXXXXXXXX

# Anthropic (AI Assistant - Claude Models) [Optional]
ANTHROPIC_API_KEY=sk-ant-XXXXXXXXXXXXXXXXXXXXXXXX

# ===================================
# Stripe Payments
# ===================================
STRIPE_SECRET_KEY=sk_test_XXXXXXXXXXXXXXXXXXXXXXXX
STRIPE_WEBHOOK_SECRET=whsec_XXXXXXXXXXXXXXXXXXXXXXXX
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_XXXXXXXXXXXXXXXXXXXXXXXX

# ===================================
# AWS S3 Storage
# ===================================
AWS_ACCESS_KEY_ID=AKIAXXXXXXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
AWS_REGION=us-east-1
AWS_BUCKET_NAME=your-bucket-name

# ===================================
# Optional Services
# ===================================
# Email (SMTP)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASS=your-password
SMTP_FROM=noreply@example.com

🔑 Variable Details

Clerk Authentication

Variable	Description	Where to Find
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Public key for client-side auth	Clerk Dashboard → API Keys
`CLERK_SECRET_KEY`	Secret key for server-side auth	Clerk Dashboard → API Keys

⚠️

Important: Clerk Webhook

Set up a webhook in Clerk pointing to /api/webhooks/clerk to sync user data with your database.

MongoDB

Variable	Description	Format
`MONGODB_URI`	Connection string to your database	`mongodb+srv://user:pass@cluster/dbname`

See the MongoDB Setup Guide for detailed instructions.

AI Services

Variable	Service	Used For
`GEMINI_API_KEY`	Google AI Studio	Quiz generation, Educator/Student tools
`OPENAI_API_KEY`	OpenAI Platform	AI Assistant (GPT-4o Mini)
`ANTHROPIC_API_KEY`	Anthropic	AI Assistant (Claude) - Optional

💡

AI Model Selection

Gemini is required for core functionality. OpenAI and Anthropic are optional but enable additional AI models in the AI Assistant.

Stripe Payments

Variable	Description	Where to Find
`STRIPE_SECRET_KEY`	Server-side API key	Stripe Dashboard → Developers → API keys
`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`	Client-side API key	Stripe Dashboard → Developers → API keys
`STRIPE_WEBHOOK_SECRET`	Webhook signing secret	Stripe Dashboard → Developers → Webhooks

See the Stripe Configuration Guide for webhook setup.

AWS S3

Variable	Description
`AWS_ACCESS_KEY_ID`	IAM user access key
`AWS_SECRET_ACCESS_KEY`	IAM user secret key
`AWS_REGION`	S3 bucket region (e.g., us-east-1)
`AWS_BUCKET_NAME`	Your S3 bucket name

✅ Verification

After setting up your environment, verify the configuration:

Start Development Server

npm run dev

Check for Errors

Look for any environment-related errors in the console

Test Authentication

Try signing up/signing in to verify Clerk is working

Test AI Features

Generate a quiz to verify Gemini API is connected

🔧 Common Issues

Error	Cause	Solution
CLERK_SECRET_KEY is missing	Environment variable not set	Add to .env.local and restart dev server
MongoDB connection failed	Invalid connection string or IP not whitelisted	Check MONGODB_URI and whitelist your IP in Atlas
AI generation fails	Invalid or missing API key	Verify GEMINI_API_KEY is correct
Stripe checkout fails	Webhook not configured	Set up webhook and STRIPE_WEBHOOK_SECRET

🔒 Security Notes

🛑

Never Commit Secrets

Never commit .env.local to version control. It's already in .gitignore. For production, use environment variable management in your hosting platform.