Skip to main content

Configuration Reference

Complete environment variable reference for SaaS Starter.

Configuration Reference

The authoritative list of all environment variables, defaults, and validation rules lives in the API codebase: apps/api/src/config.ts (Zod schema). This page is a curated summary for onboarding.

If anything on this page disagrees with the Zod schema, trust the Zod schema and email support@example.com.

Required Variables

| Variable | Description | |---|---| | NODE_ENV | development | production | test | | APP_URL | Full URL of the web app (e.g. http://localhost:3000) | | API_URL | Full URL of the API (e.g. http://localhost:8000) | | AUTH_SECRET | Session signing secret — minimum 32 characters | | BETTER_AUTH_SECRET | Better Auth session secret — minimum 32 characters | | ENCRYPTION_KEY | Encryption key for sensitive data — minimum 32 characters | | DATABASE_URL | PostgreSQL connection string | | REDIS_URL | Redis connection string (default port 6379, DB 0) | | REDIS_QUEUE_URL | Redis for BullMQ queue (default port 6379, DB 1) |

Optional Variables

App

| Variable | Default | Description | |---|---|---| | APP_NAME | SaaS Starter | Display name across the UI | | PORT | 8000 | API server port | | DEPLOY_MODE | local | local | docker |

Authentication

| Variable | Description | |---|---| | BETTER_AUTH_URL | Must match APP_URL for cookie signing | | GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | Google OAuth credentials | | GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET | GitHub OAuth credentials |

Billing

| Variable | Description | |---|---| | BILLING_PROVIDER | stripe | paddle | lemonsqueezy | polar | | Provider-specific keys | Set based on selected provider |

Email

| Variable | Default | Description | |---|---|---| | EMAIL_PROVIDER | smtp | smtp | resend | sendgrid | | EMAIL_FROM | noreply@example.com | Sender address | | EMAIL_FROM_NAME | My SaaS | Sender display name |

AI

| Variable | Default | Description | |---|---|---| | AI_PROVIDER | openai | openai | anthropic | gemini | groq | | AI_API_KEY | — | API key for selected provider | | AI_MODEL | — | Override default model | | AI_MAX_TOKENS | 2048 | Max tokens per request |

Admin

| Variable | Default | Description | |---|---|---| | ADMIN_PATH | /admin | Admin route prefix | | ADMIN_UIDS | — | Comma-separated user IDs with admin access | | SETUP_TOKEN | — | One-time setup token for /admin/setup |

Setting Up

  1. Copy .env.minimal.example to .env
  2. Generate secrets: openssl rand -hex 32
  3. Set AUTH_SECRET, BETTER_AUTH_SECRET, ENCRYPTION_KEY, SETUP_TOKEN
  4. Set DATABASE_URL and REDIS_URL for your PostgreSQL and Redis
  5. Select and configure a billing provider
  6. Run pnpm doctor to validate configuration

Validation

The API validates all variables at startup and fails fast with clear error messages.

Test your setup:

# Validate environment
pnpm doctor

# Test API health
curl http://localhost:8000/health