Skip to main content

​
Overview

GitaChat requires different environment variables for the frontend and backend services. This guide explains each variable, where to obtain the necessary API keys, and how to configure them properly.

​
Frontend Environment Variables

Create a .env.local file in the frontend/ directory with the following variables:

​
Configuration File

frontend/.env.local
BACKEND_URL=http://localhost:8000
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
CLERK_SECRET_KEY=sk_test_xxxxx
NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=xxxxx

​
Variable Reference

BACKEND_URL

Purpose: URL of the FastAPI backend serverLocal Development: http://localhost:8000Production: Your Railway deployment URL (e.g., https://your-app.up.railway.app)Required: Yes

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY

Purpose: Public key for Clerk authentication (client-side)Format: pk_test_xxxxx (test) or pk_live_xxxxx (production)Required: YesPrefix: NEXT_PUBLIC_ makes this variable accessible in the browser

CLERK_SECRET_KEY

Purpose: Secret key for Clerk authentication (server-side)Format: sk_test_xxxxx (test) or sk_live_xxxxx (production)Required: YesSecurity: Keep this secret and never expose in client-side code

NEXT_PUBLIC_SUPABASE_URL

Purpose: Supabase project URL for storing user query historyFormat: https://xxxxx.supabase.coRequired: YesPrefix: NEXT_PUBLIC_ makes this variable accessible in the browser

SUPABASE_SERVICE_ROLE_KEY

Purpose: Supabase service role key for server-side database operationsFormat: Long alphanumeric string (starts with eyJ)Required: YesSecurity: Bypasses Row Level Security (RLS) - keep confidential

​
Getting Frontend API Keys

1

Clerk Authentication

  1. Create a free account at clerk.com
  2. Create a new application
  3. Go to API Keys in the dashboard
  4. Copy the Publishable key and Secret key
  5. For production, switch to Live keys instead of Test keys
2

Supabase Database

  1. Create a free account at supabase.com
  2. Create a new project
  3. Go to Project Settings > API
  4. Copy the Project URL (for NEXT_PUBLIC_SUPABASE_URL)
  5. Copy the service_role key (for SUPABASE_SERVICE_ROLE_KEY)
The service role key is under the “Project API keys” section. Do NOT use the anon public key.

​
Backend Environment Variables

Create a .env file in the backend/ directory with the following variables:

​
Configuration File

backend/.env
PINECONE_API_KEY=xxxxx-xxxxx-xxxxx
PINECONE_INDEX=gitachat
GPT_KEY=sk-xxxxx

​
Variable Reference

PINECONE_API_KEY

Purpose: API key for Pinecone vector databaseFormat: UUID-style key with dashesRequired: YesUsed for: Storing and querying 700+ verse embeddings (768-dimensional vectors)

PINECONE_INDEX

Purpose: Name of your Pinecone index containing the Gita versesDefault: gitachatRequired: YesIndex Specs:
  • Dimensions: 768 (BGE-base-en-v1.5)
  • Metric: Cosine similarity
  • ~700 vectors (one per verse)

GPT_KEY

Purpose: OpenAI API key for generating contextual commentaryFormat: sk-xxxxxRequired: YesUsed for: Creating tailored explanations that connect verses to user questionsModel: Uses GPT-4 for high-quality contextual analysis

​
Getting Backend API Keys

1

Pinecone Vector Database

  1. Create a free account at pinecone.io
  2. Create a new project
  3. Go to API Keys and copy your API key
  4. Create a new index:
    • Name: gitachat (or your preferred name)
    • Dimensions: 768
    • Metric: cosine
  5. You’ll need to populate this index with verse embeddings
The free tier has limitations. For production use with 700+ verses, consider the Starter plan.
2

OpenAI API

  1. Create an account at platform.openai.com
  2. Go to API Keys section
  3. Click Create new secret key
  4. Copy the key immediately (it won’t be shown again)
  5. Add billing information to enable API access
GitaChat uses GPT-4 for contextual commentary. Ensure your account has access to GPT-4 API.

​
Environment Variable Templates

​
Frontend Template

.env.local.example
# Backend API URL
BACKEND_URL=http://localhost:8000

# Clerk Authentication
# Get from: https://dashboard.clerk.com
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
CLERK_SECRET_KEY=sk_test_xxxxx

# Supabase Database
# Get from: https://app.supabase.com/project/_/settings/api
NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=xxxxx

​
Backend Template

.env.example
# Pinecone Vector Database
# Get from: https://app.pinecone.io
PINECONE_API_KEY=xxxxx-xxxxx-xxxxx
PINECONE_INDEX=gitachat

# OpenAI API
# Get from: https://platform.openai.com/api-keys
GPT_KEY=sk-xxxxx

​
Validation

The backend validates all required environment variables at startup. If any are missing, you’ll see clear error messages: 
# From config.py
if not PINECONE_API_KEY:
    raise ValueError("PINECONE_API_KEY environment variable is required")
if not PINECONE_INDEX:
    raise ValueError("PINECONE_INDEX environment variable is required")
if not GPT_KEY:
    raise ValueError("GPT_KEY environment variable is required")

​
Security Best Practices

Never Commit Secrets

Add .env, .env.local, and .env.production to your .gitignore
.gitignore
.env
.env.local
.env.production

Use Different Keys

Use separate API keys for development and production environments
  • Development: Test/sandbox keys
  • Production: Live/production keys

Rotate Regularly

Periodically rotate your API keys, especially if:
  • Keys are accidentally exposed
  • Team members leave
  • Suspicious activity detected

Limit Permissions

Use the minimum required permissions:
  • Supabase: Service role only for server
  • OpenAI: Set usage limits and alerts
  • Pinecone: Read-only if not upserting

​
Environment-Specific Configuration

​
Development

# Frontend
BACKEND_URL=http://localhost:8000
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
CLERK_SECRET_KEY=sk_test_xxxxx

# Backend  
PINECONE_API_KEY=your-dev-key
PINECONE_INDEX=gitachat-dev
GPT_KEY=sk-xxxxx

​
Production

# Frontend
BACKEND_URL=https://api.gitachat.org
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_xxxxx
CLERK_SECRET_KEY=sk_live_xxxxx

# Backend
PINECONE_API_KEY=your-prod-key
PINECONE_INDEX=gitachat-prod
GPT_KEY=sk-xxxxx

​
Troubleshooting

401 Unauthorized

Symptom: Authentication errorsSolution:
  • Verify Clerk keys are correct
  • Check if using test vs. live keys
  • Ensure keys match your environment

CORS Errors

Symptom: Frontend can’t reach backendSolution:
  • Verify BACKEND_URL is correct
  • Check backend CORS configuration in main.py
  • Ensure backend is running

Pinecone Connection Failed

Symptom: Vector search not workingSolution:
  • Verify PINECONE_API_KEY is valid
  • Check PINECONE_INDEX name matches
  • Ensure index dimensions are 768

OpenAI Rate Limit

Symptom: Commentary generation failsSolution:
  • Check OpenAI account billing
  • Verify API key has GPT-4 access
  • Review rate limits and quotas

​
Next Steps

Local Setup

Complete the local development setup with these environment variables

Deployment

Configure environment variables in Vercel and Railway for production

Build docs developers (and LLMs) love

Get started for freeTalk to us