Self-Hosted Environment Variables

This page applies to the self-hosted Convex + Next.js architecture.

If you use Banata as a managed service, start in the dashboard, create a project, issue a project-scoped API key, and use @banata-auth/sdk. You do not need this Convex deployment setup for the dashboard-first path.

Banata Auth uses environment variables in two separate runtimes for self-hosting: the Convex backend (server-side) and the Next.js frontend. It's important to set each variable in the right place.

Quick Reference

Convex Environment Variables

These are set on the Convex deployment using npx convex env set. They're available to Convex functions via process.env.

Core

# Set core variables
npx convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)"
npx convex env set SITE_URL "http://localhost:3000"

Social OAuth Providers

Set these only for the providers you've enabled in socialProviders:

# Example: Set GitHub OAuth credentials
npx convex env set GITHUB_CLIENT_ID "Ov23li..."
npx convex env set GITHUB_CLIENT_SECRET "your-secret"
 
# Example: Set Google OAuth credentials
npx convex env set GOOGLE_CLIENT_ID "123456.apps.googleusercontent.com"
npx convex env set GOOGLE_CLIENT_SECRET "GOCSPX-..."

Email Provider

npx convex env set RESEND_API_KEY "re_..."

Note: You can use any email provider (SendGrid, Postmark, Mailgun, etc.) — just change the fetch() call in your email callbacks. RESEND_API_KEY is shown here because the dashboard uses Resend by default.

Passkey (WebAuthn)

npx convex env set PASSKEY_RP_ID "myapp.com"
npx convex env set PASSKEY_ORIGIN "https://myapp.com"

Listing All Convex Variables

# View all set variables
npx convex env list
 
# Remove a variable
npx convex env unset GITHUB_CLIENT_ID

Next.js Environment Variables (.env.local)

These are set in your .env.local file and are available to your Next.js app.

Core

Example .env.local

# Convex deployment
CONVEX_DEPLOYMENT=dev:your-deployment-name
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site
 
# App URL
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Local Development

For local Convex development (npx convex dev):

CONVEX_DEPLOYMENT=local:local-your-project-name
NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210
NEXT_PUBLIC_CONVEX_SITE_URL=http://127.0.0.1:3211
NEXT_PUBLIC_SITE_URL=http://localhost:3000

NEXT_PUBLIC_ Prefix

Variables starting with NEXT_PUBLIC_ are embedded in the client-side JavaScript bundle and visible to users. Never put secrets in NEXT_PUBLIC_ variables.

Dashboard-Specific Variables

The admin dashboard (apps/dashboard) uses additional variables:

Production Checklist

Before deploying to production, verify:

• BETTER_AUTH_SECRET is set to a unique, strong random value (different from development)
• SITE_URL is set to your production domain (e.g., https://myapp.com)
• NEXT_PUBLIC_CONVEX_URL points to your production Convex deployment
• NEXT_PUBLIC_CONVEX_SITE_URL points to your production Convex site URL
• OAuth callback URLs in provider dashboards are updated to production URLs
• PASSKEY_RP_ID is set to your production domain (not localhost)
• PASSKEY_ORIGIN is set to your production origin (with https://)
• Email provider API key is set and verified
• No development secrets are used in production
• .env.local is in .gitignore (never commit secrets)

Template .env.local

Copy this template for new projects:

# Convex deployment (filled by `npx convex dev`)
CONVEX_DEPLOYMENT=dev:your-deployment-name
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site
 
# App URL
NEXT_PUBLIC_SITE_URL=http://localhost:3000

And set these on Convex:

npx convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)"
npx convex env set SITE_URL "http://localhost:3000"
# Add OAuth and email provider secrets as needed

What's Next

• Deploy — Production deployment guide
• Quick Start — Set up a new project from scratch
• Convex — Backend configuration reference