Environment Variables

Codapult uses environment variables for secrets, provider selection, and per-environment configuration. Copy .env.example to .env.local and fill in the values relevant to your setup.

cp .env.example .env.local

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Never put secrets in NEXT_PUBLIC_ variables.

All env vars are accessed through src/lib/config.ts for type-safe usage in server code.

Database

| Variable | Required | Description | | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------- | | DB_PROVIDER | No | Database engine: "turso" (default) or "postgres" | | TURSO_DATABASE_URL | Yes* | Turso connection URL. Format: libsql://your-db.turso.io for cloud, or file:local.db for local development | | TURSO_AUTH_TOKEN | Yes** | Auth token for Turso cloud databases | | TURSO_API_TOKEN | No | Turso Platform API token — required for multi-region replication | | TURSO_ORG_SLUG | No | Your Turso organization slug — used with the Platform API | | DATABASE_URL | Yes*** | PostgreSQL connection string. Format: postgresql://user:password@host:5432/dbname?sslmode=require |

* Required when DB_PROVIDER=turso (the default). ** Required for Turso cloud databases. Not needed for local file: URLs. *** Required when DB_PROVIDER=postgres.

Authentication

| Variable | Required | Description | | --------------- | -------- | --------------------------------------------------------------- | | AUTH_PROVIDER | No | Auth backend: "better-auth" (default), "kinde", or "none" |

Better-Auth variables

| Variable | Required | Description | | -------------------- | -------- | ------------------------------------------------------------------ | | BETTER_AUTH_SECRET | Yes* | Session encryption secret. Generate with openssl rand -base64 32 | | BETTER_AUTH_URL | No | Auth callback base URL. Defaults to http://localhost:3000 |

* Required when AUTH_PROVIDER=better-auth (the default).

Kinde variables

| Variable | Required | Description | | -------------------------------- | -------- | ----------------------------------------------------------- | | KINDE_CLIENT_ID | Yes* | Kinde application client ID | | KINDE_CLIENT_SECRET | Yes* | Kinde application client secret | | KINDE_ISSUER_URL | Yes* | Your Kinde domain, e.g. https://your-app.kinde.com | | KINDE_SITE_URL | No | Site URL for callbacks. Defaults to http://localhost:3000 | | KINDE_POST_LOGOUT_REDIRECT_URL | No | Redirect after logout | | KINDE_POST_LOGIN_REDIRECT_URL | No | Redirect after login. Defaults to /dashboard |

* Required when AUTH_PROVIDER=kinde.

OAuth providers (Better-Auth)

| Variable | Required | Description | | ---------------------- | -------- | -------------------------------------------------- | | GOOGLE_CLIENT_ID | No | Google OAuth client ID — enable Google sign-in | | GOOGLE_CLIENT_SECRET | No | Google OAuth client secret | | GITHUB_CLIENT_ID | No | GitHub OAuth app client ID — enable GitHub sign-in | | GITHUB_CLIENT_SECRET | No | GitHub OAuth app client secret |

Payments

| Variable | Required | Description | | ------------------ | -------- | --------------------------------------------------------- | | PAYMENT_PROVIDER | No | Payment backend: "stripe" (default) or "lemonsqueezy" |

Stripe variables

| Variable | Required | Description | | ---------------------------------------- | -------- | -------------------------------------------------------------------- | | STRIPE_SECRET_KEY | Yes* | Stripe secret API key | | STRIPE_WEBHOOK_SECRET | Yes* | Webhook signing secret from Stripe dashboard | | STRIPE_CONNECT_APPLICATION_FEE_PERCENT | No | Platform fee percentage for Stripe Connect marketplace (e.g. "10") |

* Required when PAYMENT_PROVIDER=stripe (the default).

LemonSqueezy variables

| Variable | Required | Description | | ----------------------------- | -------- | -------------------------- | | LEMONSQUEEZY_API_KEY | Yes* | LemonSqueezy API key | | LEMONSQUEEZY_STORE_ID | Yes* | Your LemonSqueezy store ID | | LEMONSQUEEZY_WEBHOOK_SECRET | Yes* | Webhook signing secret |

* Required when PAYMENT_PROVIDER=lemonsqueezy.

AI

| Variable | Required | Description | | ------------------------ | -------- | --------------------------------------------------------------------- | | OPENAI_API_KEY | No | OpenAI API key — enables GPT models in AI chat | | ANTHROPIC_API_KEY | No | Anthropic API key — enables Claude models in AI chat | | EMBEDDING_PROVIDER | No | Embedding backend: "openai" (default) or "ollama" | | VECTOR_STORE_PROVIDER | No | Vector storage: "sqlite" (default) or "memory" (useful for tests) | | OLLAMA_BASE_URL | No | Ollama server URL. Defaults to http://localhost:11434 | | OLLAMA_EMBEDDING_MODEL | No | Ollama model for embeddings. Defaults to nomic-embed-text |

At least one of OPENAI_API_KEY or ANTHROPIC_API_KEY is needed to use the AI chat feature. RAG (retrieval-augmented generation) requires an embedding provider to be configured.

Email

| Variable | Required | Description | | ---------------- | -------- | ------------------------------------------------------------------------------- | | RESEND_API_KEY | Yes | Resend API key — used for transactional emails, magic links, and drip campaigns | | EMAIL_FROM | No | Default sender address. Defaults to [email protected] |

Analytics

| Variable | Required | Description | | ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- | | NEXT_PUBLIC_POSTHOG_KEY | No | PostHog project API key | | NEXT_PUBLIC_POSTHOG_HOST | No | PostHog instance URL. Defaults to https://us.i.posthog.com | | NEXT_PUBLIC_ANALYTICS_ENABLED | No | Set to "true" to enable the built-in first-party analytics module. Useful when PostHog is not configured |

Error Monitoring

| Variable | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------ | | NEXT_PUBLIC_SENTRY_DSN | No | Sentry DSN — enables client, server, and edge error tracking | | SENTRY_ORG | No | Sentry organization slug (used for source map uploads) | | SENTRY_PROJECT | No | Sentry project name | | SENTRY_AUTH_TOKEN | No | Sentry auth token (used for source map uploads during build) |

Storage

| Variable | Required | Description | | ------------------ | -------- | ------------------------------------------------------------ | | STORAGE_PROVIDER | No | File storage backend: "local" (default), "s3", or "r2" |

S3 / R2 variables

| Variable | Required | Description | | ---------------------- | -------- | -------------------------------------------------------------------- | | S3_BUCKET | Yes* | S3 bucket name | | S3_REGION | No | AWS region. Defaults to "auto" (required for R2) | | S3_ENDPOINT | Yes** | Custom S3 endpoint URL (required for R2 and S3-compatible providers) | | S3_ACCESS_KEY_ID | Yes* | Access key ID | | S3_SECRET_ACCESS_KEY | Yes* | Secret access key | | S3_PUBLIC_URL | No | Public URL prefix for uploaded files (e.g. CDN domain) |

* Required when STORAGE_PROVIDER=s3 or STORAGE_PROVIDER=r2. ** Required for Cloudflare R2 and other S3-compatible providers.

Background Jobs

| Variable | Required | Description | | ---------------- | -------- | ------------------------------------------------------------------------- | | JOB_PROVIDER | No | Job runner: "memory" (default, in-process) or "bullmq" (Redis-backed) | | REDIS_URL | Yes* | Redis connection URL, e.g. redis://localhost:6379 | | JOB_QUEUE_NAME | No | BullMQ queue name. Defaults to "codapult" |

* Required when JOB_PROVIDER=bullmq.

Use memory for development and bullmq for production workloads that need durable, concurrent job processing.

Notifications

| Variable | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------- | | NOTIFICATION_TRANSPORT | No | Server-side transport: "poll" (default), "sse", or "ws" | | NEXT_PUBLIC_WS_URL | Yes* | WebSocket server URL, e.g. ws://localhost:3001 | | WS_PORT | No | Port for the WebSocket server. Defaults to 3001 |

* Required when NOTIFICATION_TRANSPORT=ws.

Enterprise SSO (SAML)

| Variable | Required | Description | | --------------- | -------- | --------------------------------------------------------------------------- | | SSO_PROVIDER | No | SSO engine: "jackson" (BoxyHQ Jackson, default) | | SSO_PRODUCT | No | Product identifier for SSO connections. Defaults to "codapult" | | SSO_DB_ENGINE | No | Jackson storage engine: "mem" (default), "sql", "mongo", or "redis" | | SSO_DB_TYPE | No | Database type when SSO_DB_ENGINE=sql: "postgres" (default) | | SSO_DB_URL | Yes* | Database URL for Jackson persistence |

* Required when SSO_DB_ENGINE=sql (recommended for production).

For development, Jackson defaults to in-memory storage. For production, use a Postgres database for durable SSO connections.

App

| Variable | Required | Description | | ------------------------- | -------- | -------------------------------------------------------------- | | NEXT_PUBLIC_APP_URL | No | Public base URL. Defaults to http://localhost:3000 | | NEXT_PUBLIC_APP_NAME | No | App display name. Defaults to "Codapult" | | DEFAULT_MONTHLY_CREDITS | No | Monthly AI usage credits per organization. Defaults to "100" |

Support Widget

| Variable | Required | Description | | ------------------------------ | -------- | --------------------------------------------------------------------- | | NEXT_PUBLIC_SUPPORT_PROVIDER | No | Support chat provider: "crisp", "intercom", or "none" (default) | | NEXT_PUBLIC_CRISP_WEBSITE_ID | Yes* | Crisp website ID | | NEXT_PUBLIC_INTERCOM_APP_ID | Yes** | Intercom app ID |

* Required when NEXT_PUBLIC_SUPPORT_PROVIDER=crisp. ** Required when NEXT_PUBLIC_SUPPORT_PROVIDER=intercom.

OpenTelemetry

| Variable | Required | Description | | ----------------------------- | -------- | --------------------------------------------------------------------------------------- | | OTEL_EXPORTER_OTLP_ENDPOINT | No | OTLP collector endpoint, e.g. http://localhost:4318. Tracing is disabled when not set | | OTEL_SERVICE_NAME | No | Service name in traces. Defaults to "codapult" | | OTEL_TRACES_SAMPLE_RATE | No | Sampling rate from 0 to 1. Defaults to "0.1" (10%) | | OTEL_EXPORTER_OTLP_HEADERS | No | Headers for the OTLP exporter, e.g. Authorization=Bearer token |

Tips

• Start minimal. Only TURSO_DATABASE_URL, BETTER_AUTH_SECRET, and RESEND_API_KEY are needed to run the app locally.
• Use the setup wizard. Run npx @codapult/cli setup to generate .env.local interactively.
• Adapter defaults. If you omit a provider variable (e.g. AUTH_PROVIDER), Codapult falls back to the default adapter — no configuration needed.
• Conditional requirements. Variables marked "Yes*" are only required when you select their corresponding provider or feature.