Environment Variables

Overview

Your Bible requires several environment variables to function properly. Copy .env.example to .env and configure each variable according to this guide.

cp .env.example .env

Never commit your .env file to version control. It contains sensitive API keys and secrets.

Variable Categories

API.Bible

Bible content API configuration

Authentication

Better Auth and OAuth settings

Database

PostgreSQL and Convex configuration

AI & Services

Gemini AI, Redis, and other services

Required Variables

API.Bible Configuration

API_BASE_URL

string

required

Base URL for the API.Bible service.Value: https://api.scripture.api.bible/v1Usage: All Bible content requests (translations, chapters, search)How to get: This is a fixed URL. Use the value above.

API_KEY

string

required

Your API.Bible API key for authentication.Example: abc123def456...Usage: Authenticates requests to API.BibleHow to get:

Visit API.Bible
Sign up for a free account
Navigate to “API Keys” section
Create a new API key
Copy the key to your .env file

Rate Limits: Free tier includes generous limits for personal use

Authentication Configuration

BETTER_AUTH_SECRET

string

required

Secret key for Better Auth session encryption and security.Example: your_random_secret_key_hereUsage: Encrypts authentication tokens and sessionsHow to generate:

# Generate a secure random string
openssl rand -base64 32

Use a strong, randomly generated secret. Never reuse secrets across environments.

BETTER_AUTH_URL

string

required

The base URL of your application for authentication callbacks.Development: http://localhost:5173Production: https://yourdomain.comUsage: OAuth redirects, authentication callbacks

Update this value when deploying to production.

Database Configuration

DATABASE_URL

string

required

PostgreSQL connection string for Better Auth.Format: postgresql://user:password@host:port/database?sslmode=requireExample (Neon): postgresql://user:pass@ep-abc123.us-east-2.neon.tech/yourbible?sslmode=requireExample (Local): postgresql://localhost/yourbibleUsage: Stores user accounts, sessions, and auth dataHow to get:

Neon (Recommended)
Local PostgreSQL

Visit Neon.tech
Create a free account
Create a new project
Copy the connection string from your dashboard
Ensure ?sslmode=require is appended

# Install PostgreSQL
brew install postgresql  # macOS
# or
sudo apt-get install postgresql  # Ubuntu

# Start PostgreSQL
brew services start postgresql

# Create database
createdb yourbible

# Connection string
postgresql://localhost/yourbible

CONVEX_DEPLOYMENT

string

required

Your Convex deployment identifier.Example: prod:my-app-123Usage: Identifies your Convex backend deploymentHow to get: Automatically set when you run npx convex dev. You can also find it in your Convex dashboard.

This is auto-generated. Don’t manually edit unless necessary.

VITE_CONVEX_URL

string

required

Your Convex backend URL for client connections.Example: https://your-project-123.convex.cloudUsage: Client-side Convex SDK connectionHow to get:

Run npx convex dev
Convex will automatically add this to your .env
Or copy from Convex dashboard under “Settings”

Must be prefixed with VITE_ to be accessible in client-side code.

AI Configuration

GEMINI_MODEL

string

required

Google Gemini model to use for story generation.Recommended: gemini-1.5-flashAlternative: gemini-1.5-pro (higher quality, higher cost)Usage: AI-powered story generationModel Comparison:

gemini-1.5-flash: Fast, cost-effective, good quality
gemini-1.5-pro: Best quality, slower, more expensive

GEMINI_API_KEY

string

required

Your Google Gemini API key.Example: AIzaSy...Usage: Authenticates requests to Google Gemini AIHow to get:

Visit Google AI Studio
Sign in with your Google account
Click “Get API Key”
Create a new API key or use existing one
Copy the key to your .env file

Rate Limits: Free tier includes 60 requests per minute

Redis/Upstash Configuration

Redis is used for rate limiting story generation (5 stories per user per day) to manage API costs.

REDIS_URL

string

required

Redis connection URL.Example: redis://default:password@host:portUsage: Rate limiting for story generationHow to get:

Visit Upstash
Create account and new Redis database
Copy Redis URL from dashboard

KV_URL

string

required

Upstash KV (Key-Value) connection URL.Example: https://your-db.upstash.ioUsage: Alternative Redis connection methodHow to get: Found in Upstash dashboard under “REST API” section.

KV_REST_API_URL

string

required

Upstash REST API URL for Redis operations.Example: https://your-db.upstash.ioUsage: HTTP-based Redis operationsHow to get: Copy from Upstash dashboard → Your database → REST API → UPSTASH_REDIS_REST_URL

KV_REST_API_TOKEN

string

required

Authentication token for Upstash REST API.Example: AXX1AAIncDE...Usage: Authenticates Redis REST API requestsHow to get: Copy from Upstash dashboard → Your database → REST API → UPSTASH_REDIS_REST_TOKEN

KV_REST_API_READ_ONLY_TOKEN

string

required

Read-only token for Upstash REST API.Example: AnE1AAIncDE...Usage: Read-only Redis operations (security best practice)How to get: Copy from Upstash dashboard → Your database → REST API → UPSTASH_REDIS_REST_TOKEN_READ_ONLY

Optional Variables

GitHub OAuth (Optional)

GITHUB_CLIENT_ID

string

GitHub OAuth application client ID.Usage: Enables “Sign in with GitHub” functionalityHow to get:

Go to GitHub Settings → Developer settings → OAuth Apps
Click “New OAuth App”
Fill in application details:
- Application name: Your Bible
- Homepage URL: http://localhost:5173 (dev) or your production URL
- Authorization callback URL: http://localhost:5173/api/auth/callback/github
Click “Register application”
Copy the Client ID

If not set, GitHub authentication will be disabled. Users can still sign in with email/password.

GITHUB_CLIENT_SECRET

string

GitHub OAuth application client secret.Usage: Authenticates GitHub OAuth requestsHow to get:

In your GitHub OAuth App settings
Click “Generate a new client secret”
Copy the secret immediately (it won’t be shown again)

Keep this secret secure. Never expose it in client-side code or public repositories.

UploadThing (Future Feature)

UPLOADTHING_TOKEN

string

UploadThing API token for file uploads.Usage: Reserved for future file upload features (e.g., profile pictures, attachments)Status: Not currently used in the applicationHow to get:

Visit UploadThing
Create account and project
Copy token from dashboard

This is optional and not required for current functionality.

Environment Files

Development (`.env`)

# API.Bible
API_BASE_URL=https://api.scripture.api.bible/v1
API_KEY=your_api_bible_key_here

# Better Auth
BETTER_AUTH_SECRET=your_generated_secret_here
BETTER_AUTH_URL=http://localhost:5173

# Database
DATABASE_URL=postgresql://localhost/yourbible

# GitHub OAuth (Optional)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

# UploadThing (Optional)
UPLOADTHING_TOKEN=your_uploadthing_token

# Google Gemini AI
GEMINI_MODEL=gemini-1.5-flash
GEMINI_API_KEY=your_gemini_api_key_here

# Redis/Upstash
KV_URL=your_kv_url_here
KV_REST_API_URL=your_kv_rest_api_url_here
KV_REST_API_TOKEN=your_kv_rest_api_token_here
KV_REST_API_READ_ONLY_TOKEN=your_kv_rest_api_read_only_token_here
REDIS_URL=your_redis_url_here

# Convex
CONVEX_DEPLOYMENT=your_convex_deployment_here
VITE_CONVEX_URL=your_convex_url_here

Production (`.env.production`)

Production Environment Configuration

For production deployment:

Create .env.production (do not commit to git)
Update URLs to production values:
- BETTER_AUTH_URL → Your production domain
- DATABASE_URL → Production PostgreSQL instance
- CONVEX_DEPLOYMENT → Production Convex deployment
Use stronger secrets
Enable SSL/TLS where applicable
Set appropriate rate limits

Security Checklist:

All secrets are unique (not reused from development)
Database connection uses SSL (?sslmode=require)
API keys have appropriate rate limits
GitHub OAuth callback URL matches production domain
Better Auth URL uses HTTPS

Validation

The application validates required environment variables at startup. Missing or invalid variables will cause the application to fail with descriptive error messages.

Checking Your Configuration

# Start development server
pnpm dev

# If variables are missing, you'll see errors like:
# ❌ Error: API_KEY is not set
# ❌ Error: Missing Gemini API key

Testing Individual Services

# Test API.Bible connection
curl -H "api-key: YOUR_API_KEY" \
  https://api.scripture.api.bible/v1/bibles

Troubleshooting

Variable Not Found

Problem: Environment variable is not being readSolutions:

Ensure .env file exists in project root
Restart development server after editing .env
Check for typos in variable names
Verify no extra spaces around = sign
For client-side variables, ensure VITE_ prefix

Invalid API Key

Problem: API requests failing with authentication errorsSolutions:

Verify API key is correct (no extra spaces)
Check key hasn’t been revoked or expired
Confirm key has necessary permissions
Regenerate key if needed

Database Connection Failed

Problem: Cannot connect to PostgreSQLSolutions:

Verify connection string format is correct
Check database server is running
Test connection with psql or database GUI
Ensure SSL mode is correct (?sslmode=require for Neon)
Verify firewall allows connection

Convex Not Connecting

Problem: Convex sync not workingSolutions:

Ensure npx convex dev is running
Verify VITE_CONVEX_URL is correct
Check Convex deployment status in dashboard
Clear browser cache and reload
Restart both Convex and development server

Rate Limiting Not Working

Problem: Story generation rate limit not appliedSolutions:

Verify all Redis environment variables are set
Test Redis connection in Upstash dashboard
Check KV_REST_API_TOKEN is valid
Review rate limit configuration in src/lib/redis.ts

Security Best Practices

Follow these security guidelines to protect your application and API keys.

Never Commit Secrets

Add .env to .gitignore (already configured)
Use .env.example as template without real values
Never commit API keys, secrets, or passwords

Use Strong Secrets

Generate random secrets: openssl rand -base64 32
Use different secrets for development and production
Rotate secrets periodically

Limit API Key Permissions

Use read-only keys where possible
Set rate limits on API keys
Restrict API keys to specific domains in production

Secure Production Variables

Use environment variable services (Vercel, Railway, etc.)
Enable SSL/TLS for all connections
Use secrets management tools for sensitive data

Local Setup

Complete guide to setting up your development environment

Integrations

Detailed documentation for each external service

Deployment

Deploying Your Bible to production

Troubleshooting

Common issues and solutions

Contributing

Reference

Environment Variables

Overview

Variable Categories

API.Bible

Authentication

Database

AI & Services

Required Variables

API.Bible Configuration

Authentication Configuration

Database Configuration

AI Configuration

Redis/Upstash Configuration

Optional Variables

GitHub OAuth (Optional)

UploadThing (Future Feature)

Environment Files

Development (`.env`)

Production (`.env.production`)

Validation

Checking Your Configuration

Testing Individual Services

Troubleshooting

Security Best Practices

Local Setup

Integrations

Deployment

Troubleshooting

Contributing

Reference

​Overview

​Variable Categories

API.Bible

Authentication

Database

AI & Services

​Required Variables

​API.Bible Configuration

​Authentication Configuration

​Database Configuration

​AI Configuration

​Redis/Upstash Configuration

​Optional Variables

​GitHub OAuth (Optional)

​UploadThing (Future Feature)

​Environment Files

​Development (.env)

​Production (.env.production)

​Validation

​Checking Your Configuration

​Testing Individual Services

​Troubleshooting

​Security Best Practices

​Related Documentation

Local Setup

Integrations

Deployment

Troubleshooting

Overview

Variable Categories

Required Variables

API.Bible Configuration

Authentication Configuration

Database Configuration

AI Configuration

Redis/Upstash Configuration

Optional Variables

GitHub OAuth (Optional)

UploadThing (Future Feature)

Environment Files

Development (`.env`)

Production (`.env.production`)

Validation

Checking Your Configuration

Testing Individual Services

Troubleshooting

Security Best Practices

Related Documentation