Skip to content

environment-reference.md

Latest commit

 

History

History
110 lines (77 loc) · 7.33 KB

environment-reference.md

File metadata and controls

110 lines (77 loc) · 7.33 KB
title Environment reference
description Complete reference of all environment variables for configuring Tale.

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. Generate with: openssl rand -hex 32
INSTANCE_SECRET No Convex instance secret. Generate with: openssl rand -hex 32

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

AI providers

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 — SOPS-encrypted API keys (auto-generated by tale init)

Database

Variable Required Default 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.