AITracer
Docs
Environment configuration

Environment configuration

Environment variables you set to run AITracer locally, in CI, and in production. Not a hosting runbook.

This page lists what you configure so the app boots, authenticates, talks to Postgres, and optional integrations work. It does not describe how any particular team deploys or operates servers.

Start from the repository .env.example, copy to .env, and fill in real values. For production, mirror the same keys in your secret manager or orchestration config (many teams keep a private env template alongside the app).

Minimum to run locally

  • App URL (client and metadata): NEXT_PUBLIC_APP_URL (e.g. http://localhost:3000, no trailing slash).
  • Database: DATABASE_URL with postgres:// or postgresql:// (PostgreSQL only; not SQLite or MySQL).
  • Auth in dev: Either the full Auth0 block below or DEV_AUTH_BYPASS=true and NEXT_PUBLIC_DEV_AUTH_BYPASS=true (development only; never in production).

Run database schema migrations as part of your release process (see the open-source repository’s migration instructions).

Application URLs

# Public site URL (OG tags, client-side links, site config). Single canonical origin.
NEXT_PUBLIC_APP_URL=http://localhost:3000
 
# Server-side OAuth base URL(s). Optional in dev if unset; required in production when Auth0 is on.
# Comma-separated list is allowed; Auth0 redirect_uri uses the first entry only.
APP_BASE_URL=http://localhost:3000

Rules: No trailing slash. If you list multiple origins in APP_BASE_URL, each must be a full https:// or http:// URL (avoid typos like https//).

Auth0 (production and real staging)

Used by @auth0/nextjs-auth0 v4 (lib/auth0.ts). Names are fixed; do not substitute generic AUTH_* names from other templates.

AUTH0_SECRET=            # long random secret; session encryption
AUTH0_DOMAIN=            # tenant host only, e.g. dev-xxx.us.auth0.com (no https://)
AUTH0_CLIENT_ID=
AUTH0_CLIENT_SECRET=
APP_BASE_URL=            # see above; first URL + callback path must match Auth0 dashboard

Auth0 dashboard (your application):

  • Allowed Callback URLs: {first APP_BASE_URL origin}/api/auth/callback
    Examples: http://localhost:3000/api/auth/callback, https://aitracer.app/api/auth/callback
  • Allowed Logout URLs: your site origin(s), e.g. https://aitracer.app
  • Allowed Web Origins: same origins you serve the app from

Login and logout routes are /auth/login and /auth/logout; the OAuth callback is /api/auth/callback.

Optional dev-only:

AUTH0_ALLOW_INSECURE_REQUESTS=   # localhost-style Auth0 testing; false or unset in production

Legacy: AUTH0_BASE_URL / AUTH0_ISSUER_BASE_URL may appear in old .env files; v4 primarily uses AUTH0_DOMAIN and APP_BASE_URL.

Database

DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/DATABASE?sslmode=require

Use a normal PostgreSQL URI. Placeholder strings in DATABASE_URL are rejected at startup.

Email (Resend)

RESEND_API_KEY=
EMAIL_FROM="AITracer <notifications@yourdomain.com>"

In non-production Node envs, empty values may use placeholders so next dev can start; production expects real keys if you send mail.

Stripe (billing)

STRIPE_API_KEY=
STRIPE_WEBHOOK_SECRET=
 
NEXT_PUBLIC_STRIPE_PRO_MONTHLY_PLAN_ID=
NEXT_PUBLIC_STRIPE_PRO_YEARLY_PLAN_ID=
NEXT_PUBLIC_STRIPE_BUSINESS_MONTHLY_PLAN_ID=
NEXT_PUBLIC_STRIPE_BUSINESS_YEARLY_PLAN_ID=

In Stripe, set the webhook URL to your deployed origin, e.g. https://your-domain/api/webhooks/stripe.

Provider integrations (dashboard)

Storing provider credentials from the settings UI requires:

PROVIDER_CREDENTIALS_SECRET=

Use a long random value. Without it, encryption for those integrations will not run.

Optional and advanced

GITHUB_OAUTH_TOKEN=     # optional; only if you enable features that call GitHub APIs
# Some CI images split "build" and "runtime" env validation—follow your pipeline’s documented pattern if applicable.

Validation and safety

  • Production: With NODE_ENV=production and auth bypass off, the app requires valid Auth0 and public URL settings at startup.
  • Never commit real secrets or private env files. Use your secret manager or CI variables.
  • Never set DEV_AUTH_BYPASS or NEXT_PUBLIC_DEV_AUTH_BYPASS to true in production; the app refuses that configuration.

Quick checklist before go-live

  1. NEXT_PUBLIC_APP_URL and APP_BASE_URL match the HTTPS origin users hit.
  2. Auth0 Allowed Callback URLs include /api/auth/callback exactly.
  3. DATABASE_URL points at the intended Postgres and migrations have been applied.
  4. Stripe webhook URL and signing secret match your deployment.
  5. PROVIDER_CREDENTIALS_SECRET is set if you use encrypted provider credentials in the dashboard.

For exact key names, use .env.example in the open-source repository as the reference list.

Infrastructure RequirementsAccess Control