Environment reference

Tale reads its configuration from a single .env file at the repo root. About a dozen variables are mandatory at first boot; the rest tune behaviour. This page lists every variable the .env.example ships with, what it defaults to, and which surface in the product consumes it.

Groups are ordered by when you first need them: domain identity, TLS, secrets, database, instance, observability, provider encryption. If a variable changes value, restart the platform container (docker compose restart tale-platform tale-convex) for it to take effect.

How to read this page

Each group is a Name | Default | Description table. Variables marked Required must be set before docker compose up succeeds. Variables marked Optional can be left unset; the column's description names what disabling the feature does.

The .env.example file ships with inline comments that explain each variable in context; this page is the structured, grouped reference for the same set.

Domain identity (required at first boot)

The SITE_URL must match what the user types in the browser exactly. A trailing slash, a missing port, or http instead of https will break the auth callback and produce sign-in loops.

TLS

selfsigned runs Caddy with a generated cert — the browser warns, fine for development. letsencrypt requires a real domain and ports 80/443 reachable from the public Internet. external makes Caddy serve plain HTTP; an upstream reverse proxy terminates TLS.

Security secrets (required)

Replace the values that ship in .env.example before exposing the instance — they are intentionally insecure placeholders.

Database

Tale runs two Postgres databases: the operational store (db, port 5432) behind the Convex backend, and the knowledge corpus (knowledge-db, port 5433) that holds document chunks, embeddings, and crawled pages. Both are ParadeDB and share DB_PASSWORD, but they are independent — point either at external infrastructure on its own.

The auto-constructed operational form is postgresql://tale:${DB_PASSWORD}@db:5432. Convex expects this URL without a database name; the name is derived from the instance configuration. The knowledge corpus lives in tale_knowledge with the private_knowledge and public_web schemas; the Settings > Data residency UI writes a richer per-store config than these raw variables, covered in Data residency.

Observability

Setting METRICS_BEARER_TOKEN exposes two endpoints behind the token: /metrics/platform and /metrics/convex (Convex's 261 built-in metrics, which now carry the RAG and crawl timings as well). See Observability config for the scrape config.

Provider secrets encryption

When both age vars are unset, Tale stores providers/*.secrets.json as plaintext JSON at mode 0600. Reach this mode only when the host disk is encrypted at rest or the files are produced by external tooling (a Kubernetes Secret mount, a Vault template). Rotating an age key is appending the new key, re-saving each provider in the UI, then dropping the old key. See Secrets with SOPS for the full rotation walk.

The env-var key source needs no environment-level switch: a provider can read its key from an environment variable instead of a secrets file, as long as the variable is named with the reserved TALE_PROVIDER_KEY_ prefix (any other name is rejected). The mechanism — the prefix gate, resolution order, the 40-character cap, the restart requirement — is documented in Providers.

Feature flags

Optional toggles for features not enabled by default. Each flag turns one feature on or off at boot; toggling requires a restart of the platform container.

RAG retrieval tuning

Optional knobs for knowledge-base search. The in-process RAG path (Convex node-actions) re-scores results with a cross-encoder when re-ranking is on. All carry the RAG_ prefix and are read by the platform and convex containers at boot; after changing one, run docker compose restart platform convex for it to take effect.

Re-ranking ships disabled because it adds per-query latency and depends on an external endpoint. Enable it — by setting RAG_RERANKING_PROVIDER=api and pointing RAG_RERANKING_API_BASE_URL at a hosted rerank service — when retrieval precision matters more than response time. There is no in-process model to download or cache; with re-ranking off, search returns the plain merged BM25 + vector ranking.

Sessions

Leave it unset to keep the default session lifetime. When set, an idle session expires server-side once the window elapses, while an active one keeps sliding forward on each request. Org admins can tighten the effective window per organisation — never loosen it past this cap — via the session idle timeout governance policy; idle sessions under that policy are revoked by a sweep that runs about every five minutes.

Versioning

Where this fits

The variables here are the operator's contact surface; the UI surface that consumes most of them lives under Platform admin. Provider keys are the one half-and-half: the keys themselves live in providers/*.secrets.json, but the UI under Settings > Providers is how you add and rotate them in practice. The next read worth queuing is Providers — it covers the file form, the SOPS modes, and the resolve-and-failover behaviour.