Environment Variables
This page is the deployment reference for LearnHouse environment variables. The backend
loads apps/api/config/config.yaml first, then overrides matching settings from the
environment. The web app reads NEXT_PUBLIC_* values from runtime config or process.env.
The CLI-generated .env file is the recommended way to configure a self-hosted instance.
Values shown as “required” have no safe production fallback. Values shown as “unset” are optional: the feature stays disabled or uses a runtime fallback when the variable is missing.
Instance and hosting
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
LEARNHOUSE_SITE_NAME | Instance name returned by the API. | string | LearnHouse | API |
LEARNHOUSE_SITE_DESCRIPTION | Short instance description returned by the API. | string | LearnHouse is an open-source platform tailored for learning experiences. | API |
LEARNHOUSE_CONTACT_EMAIL | Contact email for the instance. | hi@learnhouse.app | API | |
LEARNHOUSE_ENV | Environment label for backend and Sentry reporting. | string | dev | API, Web |
LEARNHOUSE_DEVELOPMENT_MODE | Enables development-only API behavior such as docs routes and EE dev override. | boolean | false | API, CLI |
LEARNHOUSE_SAAS | Enables SaaS deployment mode, plan gating, and platform endpoint warnings. | boolean | false | API |
LEARNHOUSE_SELF_HOSTED | Legacy self-hosting flag used in tenancy inference. Prefer LEARNHOUSE_TENANCY. Parsed loosely: any non-empty value (including the string false) enables it, so leave it unset to keep it off. | boolean-like string | unset (off) | API |
LEARNHOUSE_USE_DEFAULT_ORG | Legacy default-org flag used in tenancy inference. Prefer LEARNHOUSE_TENANCY. Parsed loosely: any non-empty value (including the string false) enables it, so leave it unset to keep it off. | boolean-like string | unset (off) | API |
LEARNHOUSE_TENANCY | Selects single host tenancy or multi subdomain tenancy. Multi-tenancy requires EE or SaaS mode. | enum: single, multi | single unless inferred as multi-tenant | API, EE CLI |
LEARNHOUSE_DOMAIN | Public domain used for org routing, cookie decisions, and custom-domain CNAME targets. Include the port for local development. | hostname | localhost:3000 | API, CLI |
LEARNHOUSE_FRONTEND_DOMAIN | Frontend host used by the API when it needs the public frontend domain separately from the backend host. | hostname | localhost:3000 | API, EE CLI |
LEARNHOUSE_SSL | Backend-side SSL flag for generated URLs and hosting config. | boolean | false | API |
LEARNHOUSE_PORT | Backend port. Local config defaults to 1338; the production CLI template emits 9000. | integer | 1338 locally, 9000 in generated Docker installs | API, CLI, API container |
LEARNHOUSE_ALLOWED_ORIGINS | Comma-separated CORS allowlist. | CSV of URLs | http://localhost:3000,http://localhost:3001 | API |
LEARNHOUSE_ALLOWED_REGEXP | Additional CORS origin regex used by multi-tenant deployments. | regex string | \b((?:https?://)[^\s/$.?#].[^\s]*)\b | API |
LEARNHOUSE_COOKIE_DOMAIN | Cookie domain for auth cookies. Use a leading dot only when subdomains must share auth. | hostname | .localhost | API, CLI |
LEARNHOUSE_COOKIE_DOMAIN_ALLOW_BROAD | Acknowledges intentionally broad cookie domains such as .example.com and silences the safety warning. | boolean | false | API, EE CLI |
LEARNHOUSE_CUSTOM_DOMAIN_DEV_MODE | Skips DNS verification for all custom domains and marks them verified immediately. Development/testing only. | boolean | false | API |
LEARNHOUSE_PUBLIC | Docker build argument that produces a community build by excluding non-community code. | boolean | false | Dockerfiles (root, API, Web) |
LEARNHOUSE_PLATFORM_URL | Base URL for LearnHouse platform links, upgrade URLs, and email allowlist checks. | URL | unset; backend flows fall back to https://www.learnhouse.app and the web token-exchange to https://learnhouse.app | API, Web |
LEARNHOUSE_PLATFORM_API_KEY | Shared secret for platform-only internal endpoints such as packs. | secret string | required for SaaS/platform endpoints | API |
CLOUD_INTERNAL_KEY | Shared secret for SaaS-internal endpoints (custom-domain sync and the cloud_internal router). When unset, those endpoints reject every request and the API logs a startup warning. | secret string | unset; required for SaaS custom-domain provisioning | API |
Database, Redis, and collaboration
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
LEARNHOUSE_SQL_CONNECTION_STRING | PostgreSQL connection string for the API and Alembic migrations. | PostgreSQL URL | postgresql://learnhouse:learnhouse@localhost:5432/learnhouse; production installs should set it | API, API migrations, CLI |
LEARNHOUSE_DB_URL | Fallback database URL for the standalone apps/api/scripts/migrate.py migration helper when DATABASE_URL is unset. | PostgreSQL URL | postgresql://learnhouse:learnhouse@localhost:5432/learnhouse | API migration script |
LEARNHOUSE_PGBOUNCER | Forces PgBouncer/Supavisor-safe asyncpg settings even when the URL does not reveal a pooler. | boolean | false | API |
LEARNHOUSE_REDIS_CONNECTION_STRING | Redis URL for the API cache/session/event clients. | Redis URL | redis://localhost:6379/learnhouse | API, CLI |
LEARNHOUSE_REDIS_URL | Redis URL for the collaboration server. | Redis URL | redis://localhost:6379; CLI setup emits redis://redis:6379 | Collab, CLI |
LEARNHOUSE_API_URL | API base URL used by the collaboration server. | URL | http://localhost:8000; generated compose sets http://localhost:9000 | Collab, CLI |
Security, setup, and auth
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
LEARNHOUSE_AUTH_JWT_SECRET_KEY | JWT signing key shared by the API and collaboration server. Must be at least 32 characters. | secret string | required | API, Collab, CLI |
LEARNHOUSE_INITIAL_ADMIN_EMAIL | Initial admin email used by the API install command and generated .env files. | admin@school.dev for the API install command; CLI setup writes the chosen email | API, CLI | |
LEARNHOUSE_INITIAL_ADMIN_PASSWORD | Initial admin password used by the API install command and generated .env files. | secret string | required for install/bootstrap | API, CLI |
LEARNHOUSE_INITIAL_ORG_NAME | Initial organization display name used during install. | string | Default Organization | API, CLI |
LEARNHOUSE_INITIAL_ORG_SLUG | Initial organization slug used during install. | slug string | default | API, CLI |
LEARNHOUSE_GOOGLE_CLIENT_ID | Google OAuth client ID used by web auth proxy routes. | string | unset unless Google OAuth is enabled | Web, CLI |
LEARNHOUSE_GOOGLE_CLIENT_SECRET | Google OAuth client secret used by the web token exchange route. | secret string | unset unless Google OAuth is enabled | Web, CLI |
LEARNHOUSE_GOOGLE_OAUTH_CLIENT_ID | Expected Google OAuth audience for backend ID-token validation. If unset, audience verification is disabled with a warning. | string | unset | API |
Web runtime
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
NEXT_PUBLIC_LEARNHOUSE_API_URL | Explicit API URL for frontend API calls. If unset, the web app derives it from NEXT_PUBLIC_LEARNHOUSE_BACKEND_URL. | URL | derived as {backend}/api/v1/ | Web, CLI |
NEXT_PUBLIC_LEARNHOUSE_BACKEND_URL | Backend base URL used by the web app and server-side auth proxy routes. | URL | http://localhost/ in config helpers; local dev checker writes http://localhost:1338/ | Web, CLI |
NEXT_PUBLIC_LEARNHOUSE_DOMAIN | Public frontend domain. The web app can also fall back to runtime cookies set by the backend. | hostname | localhost or runtime cookie fallback | Web, CLI |
NEXT_PUBLIC_LEARNHOUSE_TOP_DOMAIN | Top-level/root domain used for cookie and subdomain helpers. | hostname | derived from NEXT_PUBLIC_LEARNHOUSE_DOMAIN when unset | Web, CLI |
NEXT_PUBLIC_LEARNHOUSE_MULTI_ORG | Legacy public multi-org flag generated by the CLI. Backend LEARNHOUSE_TENANCY is authoritative for current behavior. | boolean | false | CLI, legacy Web config |
NEXT_PUBLIC_LEARNHOUSE_DEFAULT_ORG | Default organization slug used by frontend routing fallbacks. | slug string | default | Web, CLI |
NEXT_PUBLIC_LEARNHOUSE_HTTPS | Selects https:// instead of http:// in frontend URL helpers. | boolean | false | Web, CLI |
NEXT_PUBLIC_LEARNHOUSE_MEDIA_URL | Base URL for direct media links. If unset, media URLs use the backend URL. | URL | unset, falls back to backend URL | Web |
NEXT_PUBLIC_UNSPLASH_ACCESS_KEY | Unsplash API access key for the in-editor Unsplash image picker (course thumbnails, board/community thumbnails, editor image blocks, and more). The picker still renders when unset, but Unsplash searches return nothing. | string | unset | Web, CLI |
NEXT_PUBLIC_LEARNHOUSE_PLATFORM_URL | Browser-safe platform base URL for upgrade and auth exchange flows. | URL | unset | Web |
NEXT_PUBLIC_LEARNHOUSE_SENTRY_DSN | Browser/server Sentry DSN for the web app. | URL | unset | Web |
NEXT_PUBLIC_LEARNHOUSE_ENV | Web Sentry environment label. | string | dev | Web |
AI
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
LEARNHOUSE_IS_AI_ENABLED | Master switch for AI features. | boolean | false | API, CLI |
LEARNHOUSE_GEMINI_API_KEY | Legacy Google/Gemini key and fallback embeddings key for providers without embeddings. | secret string | unset | API, CLI |
LEARNHOUSE_AI_PROVIDER | Provider for generation: google, openai, anthropic, deepseek, moonshot, mistral, openrouter, bedrock, ollama, or another supported Pydantic AI provider. | string | google | API |
LEARNHOUSE_AI_API_KEY | API key for the selected AI provider. Not required for ollama; optional for bedrock. | secret string | unset; required for most providers | API |
LEARNHOUSE_AI_BASE_URL | Custom endpoint for OpenAI-compatible or local providers. | URL | unset; Ollama falls back to http://localhost:11434/v1 | API |
LEARNHOUSE_AI_MODEL_FAST | Low-latency model tier for titles, follow-ups, and migration tasks. | model id | gemini-3.1-flash-lite | API |
LEARNHOUSE_AI_MODEL_STANDARD | Standard model tier for chat, RAG, and standard-plan generation. | model id | gemini-3.5-flash | API |
LEARNHOUSE_AI_MODEL_PRO | Pro model tier for upgraded course planning and generation flows. | model id | gemini-3.1-pro-preview | API |
LEARNHOUSE_AI_EMBEDDING_PROVIDER | Optional provider override for RAG embeddings. | string | same as LEARNHOUSE_AI_PROVIDER | API |
LEARNHOUSE_AI_EMBEDDING_MODEL | Optional embedding model override. | model id | provider default, such as gemini-embedding-001, text-embedding-3-small, or nomic-embed-text | API |
LEARNHOUSE_AI_EMBEDDING_DIMENSIONS | Embedding vector size. Changing this requires a matching database migration and re-index. | integer | 768 | API |
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
LEARNHOUSE_EMAIL_PROVIDER | Outbound email provider. | enum: resend, smtp | resend | API, CLI |
LEARNHOUSE_RESEND_API_KEY | Resend API key when LEARNHOUSE_EMAIL_PROVIDER=resend. | secret string | unset; required to send via Resend | API, CLI |
LEARNHOUSE_SYSTEM_EMAIL_ADDRESS | Sender address for system email. | unset; CLI setup can emit noreply@{domain} | API, CLI | |
LEARNHOUSE_SMTP_HOST | SMTP server hostname when LEARNHOUSE_EMAIL_PROVIDER=smtp. | hostname | unset | API, CLI |
LEARNHOUSE_SMTP_PORT | SMTP server port. | integer | 587 | API, CLI |
LEARNHOUSE_SMTP_USERNAME | SMTP authentication username. | string | unset | API, CLI |
LEARNHOUSE_SMTP_PASSWORD | SMTP authentication password. | secret string | unset | API, CLI |
LEARNHOUSE_SMTP_USE_TLS | Enables TLS for SMTP. | boolean | true | API, CLI |
Content storage
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
LEARNHOUSE_CONTENT_DELIVERY_TYPE | Storage backend for uploaded content. | enum: filesystem, s3api | filesystem | API, CLI |
LEARNHOUSE_S3_API_BUCKET_NAME | S3-compatible bucket name when using s3api. | string | unset; required for S3 storage | API, CLI |
LEARNHOUSE_S3_API_ENDPOINT_URL | S3-compatible endpoint URL. Leave unset for provider defaults where supported. | URL | unset | API, CLI |
Payments
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
LEARNHOUSE_STRIPE_SECRET_KEY | Stripe secret key. | secret string | unset | API |
LEARNHOUSE_STRIPE_PUBLISHABLE_KEY | Stripe publishable key. | string | unset | API |
LEARNHOUSE_STRIPE_WEBHOOK_STANDARD_SECRET | Signing secret for the standard Stripe webhook endpoint. | secret string | unset | API |
LEARNHOUSE_STRIPE_WEBHOOK_CONNECT_SECRET | Signing secret for the Stripe Connect webhook endpoint. | secret string | unset | API |
LEARNHOUSE_STRIPE_CLIENT_ID | Stripe Connect OAuth client ID. | string | unset | API |
Code execution and analytics
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
LEARNHOUSE_JUDGE0_API_URL | Judge0 API URL. Setting it enables code execution routes. | URL | unset | API |
LEARNHOUSE_JUDGE0_CLIENT_ID | Optional Judge0 client ID. | string | unset | API |
LEARNHOUSE_JUDGE0_CLIENT_SECRET | Optional Judge0 client secret. | secret string | unset | API |
LEARNHOUSE_TINYBIRD_API_URL | Tinybird regional API URL. Setting it enables analytics config. | URL | unset | API |
LEARNHOUSE_TINYBIRD_INGEST_TOKEN | Tinybird token with ingest/write permissions. | secret string | unset; required for event ingestion | API |
LEARNHOUSE_TINYBIRD_READ_TOKEN | Tinybird token with read/query permissions. | secret string | unset; required for analytics reads | API |
Observability
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
LEARNHOUSE_SENTRY_DSN | Backend Sentry DSN; also used by the web edge Sentry config as a non-public fallback. | URL | unset | API, Web edge |
LEARNHOUSE_LOGFIRE_ENABLED | CLI-generated Logfire flag. The current OSS runtime does not read it directly. | boolean | False in CLI-generated .env | CLI |
Enterprise and development controls
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
LEARNHOUSE_LICENSE_KEY | Enterprise license key. Validated by the EE backend at runtime; the CLI passes it through during install/update. | secret string | required for EE installs and updates | EE backend, EE CLI |
LEARNHOUSE_LICENSE_SERVER_URL | Enterprise license server URL. | URL | https://partners.learnhouse.app | EE backend, EE CLI |
LEARNHOUSE_LICENSE_GRACE_HOURS | Offline grace period (hours) the EE backend allows before an unvalidated license is rejected. | integer | 25 (max 168) | EE backend |
LEARNHOUSE_DATA_DIR | Data directory path inside the Enterprise backend container. | path | /app/data | EE backend container |
LEARNHOUSE_DISABLE_EE | Disables local Enterprise hooks even if the ee/ folder exists. | boolean-like string | unset; CLI dev sets 1 unless --ee is used | API, CLI dev |
LEARNHOUSE_FORCE_EE | Forces EE mode during development when EE code is present. Ignored unless development mode is enabled. | boolean-like string | unset | API, CLI dev |
WORKOS_API_KEY | WorkOS API key for Enterprise SSO. Required (with WORKOS_CLIENT_ID) to enable WorkOS-backed SSO. | secret string | unset; required for SSO | EE backend |
WORKOS_CLIENT_ID | WorkOS client ID for Enterprise SSO. | string | unset; required for SSO | EE backend |
SSO_REDIRECT_URI | Full SSO callback URL override. When set, it is used as-is. | URL | unset; derived from SSO_REDIRECT_URI_BASE / the configured domain | EE backend |
SSO_REDIRECT_URI_BASE | Base URL used to build the SSO callback when SSO_REDIRECT_URI is not set. | URL | unset; falls back to LEARNHOUSE_DOMAIN, then to http://localhost:4000 | EE backend |
Related generated variables
These variables do not use the LEARNHOUSE_ prefix, but the CLI writes them into the same
.env file and several services require them.
| Variable | Description | Type | Default / required | Used by |
|---|---|---|---|---|
HTTP_PORT | Public HTTP port chosen during CLI setup. | integer | setup choice | CLI-generated compose |
NEXTAUTH_URL | Base URL for NextAuth-compatible auth helpers. | URL | generated from the configured domain | CLI, doctor |
NEXTAUTH_SECRET | Secret used by NextAuth-compatible auth helpers. | secret string | generated by CLI setup | CLI, doctor |
COLLAB_INTERNAL_KEY | Shared key for API-to-collaboration-server internal auth. | secret string | required for dev and production collab auth | API, Collab, CLI |
NEXT_PUBLIC_COLLAB_URL | Public WebSocket URL for the collaboration server. | WebSocket URL | generated from the configured domain | Web, CLI |
COLLAB_PORT | Local collaboration server port. | integer | 4000 in local dev checker | Collab, CLI dev |
COLLAB_TRUST_PROXY | Set to true when the collaboration server runs behind a reverse proxy so client IPs (used for WebSocket rate limiting) are read from X-Forwarded-For. | boolean | false | Collab |
POSTGRES_USER | PostgreSQL user for generated non-external database installs. | string | learnhouse | CLI-generated compose |
POSTGRES_PASSWORD | PostgreSQL password for generated non-external database installs. | secret string | generated by CLI setup | CLI-generated compose |
POSTGRES_DB | PostgreSQL database name for generated non-external database installs. | string | learnhouse | CLI-generated compose |
Full example
.env
# Domain and hosting
LEARNHOUSE_DOMAIN=learn.example.com
HTTP_PORT=443
NEXT_PUBLIC_LEARNHOUSE_BACKEND_URL=https://learn.example.com/
NEXT_PUBLIC_LEARNHOUSE_API_URL=https://learn.example.com/api/v1/
NEXT_PUBLIC_LEARNHOUSE_DOMAIN=learn.example.com
NEXT_PUBLIC_LEARNHOUSE_TOP_DOMAIN=example.com
NEXT_PUBLIC_LEARNHOUSE_HTTPS=true
NEXT_PUBLIC_LEARNHOUSE_DEFAULT_ORG=default
# Backend
LEARNHOUSE_SQL_CONNECTION_STRING=postgresql://learnhouse:change-me@db:5432/learnhouse
LEARNHOUSE_REDIS_CONNECTION_STRING=redis://redis:6379/learnhouse
LEARNHOUSE_COOKIE_DOMAIN=.example.com
LEARNHOUSE_PORT=9000
# Security and bootstrap
LEARNHOUSE_AUTH_JWT_SECRET_KEY=replace-with-at-least-32-random-characters
LEARNHOUSE_INITIAL_ADMIN_EMAIL=admin@example.com
LEARNHOUSE_INITIAL_ADMIN_PASSWORD=change-this-password
LEARNHOUSE_INITIAL_ORG_NAME=Default Organization
LEARNHOUSE_INITIAL_ORG_SLUG=default
# Collaboration
COLLAB_INTERNAL_KEY=replace-with-random-shared-secret
LEARNHOUSE_REDIS_URL=redis://redis:6379
NEXT_PUBLIC_COLLAB_URL=wss://learn.example.com/collab
# AI, email, and storage
LEARNHOUSE_IS_AI_ENABLED=False
LEARNHOUSE_EMAIL_PROVIDER=resend
LEARNHOUSE_CONTENT_DELIVERY_TYPE=filesystem