Environment Variables

Reference for all environment variables, where each one belongs, and what it does.

OpenSana uses environment variables across three different contexts. Each variable belongs in a specific place — setting it in the wrong place has no effect.

Where Each Variable Goes

Variable	Convex Dashboard	Web Hosting (Vercel, etc.)	Local `.env.local`
`CLERK_JWT_ISSUER_DOMAIN`	Yes	—	—
`RESEND_API_KEY`	Yes	—	—
`EMAIL_FROM`	Yes	—	—
`CONVEX_DEPLOY_KEY`	—	Yes (if integrated build)	—
`NEXT_PUBLIC_CONVEX_URL`	—	Yes (if separate deploy)	Yes
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	—	Yes	Yes
`CLERK_SECRET_KEY`	—	Yes	Yes
`NEXT_PUBLIC_CLERK_SIGN_IN_URL`	—	Yes	Yes
`NEXT_PUBLIC_CLERK_SIGN_UP_URL`	—	Yes	Yes
`NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL`	—	Yes	Yes
`NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL`	—	Yes	Yes
`NEXT_PUBLIC_APP_URL`	—	Yes	—
`CONVEX_DEPLOYMENT`	—	—	Yes

Convex Dashboard Variables

Set these in the Convex dashboard under Settings → Environment Variables for your deployment. They run inside Convex functions at runtime.

Variable	Required	Purpose
`CLERK_JWT_ISSUER_DOMAIN`	Yes	Clerk JWT issuer domain for token verification
`RESEND_API_KEY`	No	Resend API key for transactional email
`EMAIL_FROM`	No	Verified sender identity (e.g. `OpenSana <noreply@example.com>`)

Web Hosting Variables

Set these in your web hosting provider (Vercel, Cloudflare, etc.). They are used by the Next.js app at build time and runtime.

Variable	Required	Purpose
`CONVEX_DEPLOY_KEY`	If integrated build	Deploy key for CI/CD Convex deploys (Settings → General → Deploy Keys)
`NEXT_PUBLIC_CONVEX_URL`	If separate deploy	Convex deployment URL (e.g. `https://friendly-wolf-872.convex.cloud`)
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Yes	Clerk publishable key for browser auth
`CLERK_SECRET_KEY`	Yes	Clerk server-side secret
`NEXT_PUBLIC_CLERK_SIGN_IN_URL`	Yes	Sign-in route (typically `/auth/sign-in`)
`NEXT_PUBLIC_CLERK_SIGN_UP_URL`	Yes	Sign-up route (typically `/auth/sign-up`)
`NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL`	Yes	Post-sign-in redirect (typically `/auth/callback`)
`NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL`	Yes	Post-sign-up redirect (typically `/auth/callback`)
`NEXT_PUBLIC_APP_URL`	No	Base URL for deep links and email links

When using the integrated Convex build command (npx convex deploy --cmd 'next build' --cmd-url-env-var-name NEXT_PUBLIC_CONVEX_URL), the NEXT_PUBLIC_CONVEX_URL is injected automatically and does not need to be set separately. See Deploy to Vercel for details.

Convex Deploy Variables

These are used on the command line or in CI when deploying Convex functions. They are not set in the Convex dashboard or in your web hosting provider.

Variable	Purpose
`CONVEX_DEPLOYMENT`	Target deployment with prefix: `prod:` for production, `dev:` for development (e.g. `prod:friendly-wolf-872`)
`CONVEX_DEPLOY_KEY`	Deploy key from the Convex dashboard (Settings → General → Deploy Keys). Includes auth — useful for CI/CD

Use one or the other. See Deploy the Convex Backend for usage examples.

Local Development

For local development, apps/web/.env.local only needs:

CONVEX_DEPLOYMENT=dev:your-dev-deployment-123
NEXT_PUBLIC_CONVEX_URL=https://your-dev-deployment-123.convex.cloud

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/auth/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/auth/sign-up
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/auth/callback
NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/auth/callback

The dev: prefix indicates a development deployment. Production deployments use prod: instead.

Convex server-side variables (CLERK_JWT_ISSUER_DOMAIN, RESEND_API_KEY, EMAIL_FROM) go in the Convex dashboard for your dev deployment — they are not needed in .env.local.

Guidance

Keep secrets out of the repo
Make NEXT_PUBLIC_APP_URL match the real user-facing URL
Verify that the Convex deployment URL matches the environment users are actually signing into
Convex dashboard env vars and Next.js env vars serve different runtimes — configure both