Skip to Content
Environment Variables

Environment Variables

Use apps/web/.env.local.example as the tracked contract for the local web app.

Run bun run dev:convex to connect the repo to your hosted Convex dev deployment. That command writes NEXT_PUBLIC_CONVEX_URL and CONVEX_DEPLOYMENT into apps/web/.env.local.

Core public runtime

  • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: lets the browser talk to Clerk
  • NEXT_PUBLIC_CLERK_SIGN_IN_URL: must stay /sign-in because the app uses a custom Clerk sign-in route
  • NEXT_PUBLIC_CONVEX_URL: lets the browser talk to Convex
  • NEXT_PUBLIC_CONVEX_SITE_URL: optional but important for Convex HTTP actions like observability ingest and incident status control when the deployment serves browser traffic on .convex.cloud and HTTP actions on .convex.site

Convex CLI target

  • CONVEX_DEPLOYMENT: written by convex dev into apps/web/.env.local so repo scripts and convex run commands target your hosted Convex dev deployment explicitly

Core server runtime

  • APP_BASE_URL: canonical app URL for checkout success and cancel redirects
  • CLERK_AUTHORIZED_PARTIES: optional comma-separated origin allowlist passed to Clerk middleware for subdomain cookie-leak protection
  • CLERK_SECRET_KEY: server-side Clerk access
  • CLERK_FRONTEND_API_URL: Clerk frontend API domain used by the auth chain
  • CLERK_WEBHOOK_SIGNING_SECRET: verifies Clerk webhook requests sent to /api/observability/clerk
  • OBSERVABILITY_INGEST_TOKEN: shared random secret used by Next.js to authenticate error-ingest requests into Convex
  • OBSERVABILITY_INCIDENT_CONTROL_TOKEN: separate bearer token for the maintainer-only incident status route at /api/observability/incidents/[incidentId]/status
  • OBSERVABILITY_VERCEL_WEBHOOK_SECRET: verifies Vercel deployment webhooks sent to /api/observability/vercel
  • STRIPE_SECRET_KEY: Stripe API access
  • STRIPE_WEBHOOK_SECRET: verifies the Stripe webhook
  • STRIPE_PRICE_ID: optional dashboard-managed price
  • STRIPE_PRODUCT_ID: optional product id emitted by the Stripe script

Telegram observability

  • TELEGRAM_BOT_TOKEN: Telegram bot token used for production alerts
  • TELEGRAM_CHAT_ID: chat or group id that receives alerts
  • ENABLE_OBSERVABILITY_TEST_TRIGGER: test-only switch for the Playwright protected-shell failure harness

OBSERVABILITY_INGEST_TOKEN is not provided by Telegram, Clerk, Stripe, or Convex. It is just a high-entropy shared secret between the Next.js app and the Convex HTTP ingest route. Generate one with openssl rand -hex 32 and set the same value in both runtimes.

In production, NEXT_PUBLIC_CONVEX_URL alone is not enough for the observability system if the deployment’s HTTP actions live on a separate .convex.site origin. Set NEXT_PUBLIC_CONVEX_SITE_URL to the matching .convex.site hostname so /observability/events and /observability/incidents/status reach the real backend.

Optional video pipeline

  • AUPHONIC_API_KEY
  • AUPHONIC_PRESET_ID
  • BUNNY_STREAM_API_KEY
  • BUNNY_STREAM_LIBRARY_ID
  • VIDEO_PIPELINE_PYTHON_BIN

Optional Codex app-server integration

  • CODEX_BINARY
  • CODEX_APP_SERVER_ENABLED
  • CODEX_APP_SERVER_HOME_ROOT
  • CODEX_APP_SERVER_MODEL
  • CODEX_APP_SERVER_TIMEOUT_MS

Optional QA helpers

  • CLERK_TEST_USER_SCOPE
  • QA_COURSE_SLUG

Practical rule

Only set what the current flow actually needs. The app does not require every optional variable on day one.

Last updated on
Route MapCommands