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.