Environment reference

Complete reference of all environment variables for configuring Tale.

5 min read

All configuration is done through environment variables in the .env file. Copy .env.example to .env and fill in your values.

Domain configuration

Variable	Required	Default	Description
`HOST`	Yes	`tale.local`	Hostname without protocol (used for Docker networking and emails)
`SITE_URL`	Yes	`https://tale.local`	Full canonical URL with protocol (used for external links and auth callbacks)
`BASE_PATH`	No		Base path for subpath deployments (e.g., `/app`). Leave empty for root deployments

SITE_URL must match the URL users access in their browser, including any non-standard ports (e.g., https://example.com:8443).

TLS/SSL

Variable	Required	Default	Description
`TLS_MODE`	No	`selfsigned`	Certificate handling: `selfsigned`, `letsencrypt`, or `external`
`TLS_EMAIL`	No		Email for Let's Encrypt notifications (recommended for production)

selfsigned: Self-signed certificates for development. Browser shows a warning.
letsencrypt: Free trusted certificates from Let's Encrypt. Requires a valid public domain and ports 80/443 accessible.
external: TLS handled by an external reverse proxy. Caddy listens on HTTP only.

Security secrets

Variable	Required	Description
`BETTER_AUTH_SECRET`	Yes	Auth session signing key. Generate with: `openssl rand -base64 32`
`ENCRYPTION_SECRET_HEX`	Yes	Encryption key for sensitive data, including DB-stored guardrails secrets (moderation API keys, etc.). Generate with: `openssl rand -hex 32`. Rotating this value invalidates all stored guardrails secrets — Admins must re-save them via the UI.
`INSTANCE_SECRET`	No	Convex instance secret. Generate with: `openssl rand -hex 32`
`SOPS_AGE_KEY`	No	Age secret key for SOPS encryption of `providers/*.secrets.json`. When set, provider secrets are stored encrypted; when unset, they are stored plaintext at file mode `0600`. Auto-generated by `tale init`.
`SOPS_AGE_KEY_FILE`	No	Alternative to `SOPS_AGE_KEY`: path to a file containing the age secret key. Either env var enables encrypted mode for provider secrets.

Important: The .env.example ships with example secrets. You must replace them with your own generated values before starting, even in local development.

AI provider configuration (API keys, base URLs, models) is managed through provider files in the providers/ directory, not environment variables. See the Settings > Providers page in the management UI or edit provider JSON files directly.

providers/<name>.json — public config (base URL, models, tags)
providers/<name>.secrets.json — API key. Encrypted with SOPS when SOPS_AGE_KEY is set; otherwise plaintext at mode 0600. Auto-created by tale init and by the Settings UI.

Database

Variable	Required	Description
`DB_PASSWORD`	Yes	Password for the self-hosted PostgreSQL database
`POSTGRES_URL`	No	Override the auto-generated database connection URL. If not set, constructed as `postgresql://tale:${DB_PASSWORD}@db:5432`
`RAG_DATABASE_URL`	No	Override database URL for the RAG service (must include database name, e.g. `postgresql://...host/tale_knowledge`)
`CRAWLER_DATABASE_URL`	No	Override database URL for the Crawler service (must include database name, e.g. `postgresql://...host/tale_knowledge`)

To use an external PostgreSQL instance instead of the bundled container, see Using an external database.

Error tracking

Variable	Required	Default	Description
`SENTRY_DSN`	No		Sentry DSN for error tracking. Compatible with GlitchTip and Bugsink

If not set, error tracking is disabled and errors only appear in Docker logs.

Monitoring

Variable	Required	Default	Description
`METRICS_BEARER_TOKEN`	No		Bearer token for external access to Prometheus metrics

When unset, all /metrics/* endpoints return 401. See Operations for endpoint details.

Service URLs

These are automatically configured in Docker Compose but can be overridden for custom setups:

Variable	Default	Description
`CRAWLER_URL`	`http://crawler:8002`	Crawler service for website crawling
`RAG_URL`	`http://rag:8001`	RAG service for document indexing and search

Docker deployment

Variable	Required	Default	Description
`PULL_POLICY`	No		Set to `always` to use pre-built images from GitHub
`VERSION`	No		Image version tag (e.g., `latest`, `v1.0.0`). Used with `PULL_POLICY=always`

Microsoft Entra ID SSO

These variables are only needed if you configure SSO through environment variables instead of the in-app Settings > Integrations UI.

Variable	Required	Description
`AUTH_MICROSOFT_ENTRA_ID_ID`	No	Microsoft Entra ID application (client) ID
`AUTH_MICROSOFT_ENTRA_ID_SECRET`	No	Microsoft Entra ID client secret
`AUTH_MICROSOFT_ENTRA_ID_TENANT_ID`	No	Microsoft Entra ID tenant ID

Trusted headers authentication

Variable	Required	Description
`TRUSTED_HEADERS_ENABLED`	No	Set to `true` to enable trusted headers authentication
`TRUSTED_HEADERS_INTERNAL_SECRET`	No	Shared secret for validating trusted header requests (defense-in-depth)
`TRUSTED_EMAIL_HEADER`	No	Header name for the user's email (default: `Remote-Email`)
`TRUSTED_NAME_HEADER`	No	Header name for the user's display name (default: `Remote-Name`)
`TRUSTED_ROLE_HEADER`	No	Header name for the user's role (default: `Remote-Role`)
`TRUSTED_TEAMS_HEADER`	No	Header name for the user's teams (default: `Remote-Teams`)

See the Authentication guide for details on configuring trusted headers.

Edit on GitHub