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 |
Error tracking
| Variable | Required | Default | Description |
|---|
SENTRY_DSN | No | | Sentry DSN for error tracking. Compatible with GlitchTip and Bugsink |
Monitoring
| Variable | Required | Default | Description |
|---|
METRICS_BEARER_TOKEN | No | | Bearer token for external access to Prometheus metrics |
/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 |
| 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 |
Last modified on April 3, 2026
