Umgebungsvariablen-Referenz

Tale liest seine Konfiguration aus einer einzigen .env-Datei im Repo-Stammverzeichnis. Etwa ein Dutzend Variablen sind beim ersten Boot Pflicht; der Rest stimmt das Verhalten ab. Diese Seite listet jede Variable, die .env.example mitbringt, was sie als Default hat und welche Oberfläche im Produkt sie konsumiert.

Gruppen sind danach geordnet, wann du sie zuerst brauchst: Domain-Identität, TLS, Secrets, Datenbank, Instanz, Observability, Provider-Verschlüsselung. Ändert sich der Wert einer Variable, starte den Plattform-Container neu (docker compose restart tale-platform tale-convex), damit sie wirkt.

Wie du diese Seite liest

Jede Gruppe ist eine Name | Default | Beschreibung-Tabelle. Variablen, die als Pflicht markiert sind, müssen gesetzt sein, damit docker compose up erfolgreich ist. Optionale Variablen können unset bleiben; die Beschreibung benennt, was das Deaktivieren des Features bedeutet.

Die .env.example-Datei bringt Inline-Kommentare mit, die jede Variable im Kontext erklären; diese Seite ist die strukturierte, gruppierte Referenz für dieselbe Menge.

Domain-Identität (Pflicht beim ersten Boot)

Die SITE_URL muss exakt mit dem übereinstimmen, was der Benutzer im Browser eingibt. Ein nachgestellter Slash, ein fehlender Port oder http statt https brechen den Auth-Callback und produzieren Sign-in-Schleifen.

TLS

selfsigned lässt Caddy mit einem generierten Cert laufen — der Browser warnt, in Ordnung für Development. letsencrypt braucht eine echte Domain und Ports 80/443 vom öffentlichen Internet erreichbar. external lässt Caddy nur HTTP servieren; ein vorgelagerter Reverse-Proxy terminiert TLS.

Sicherheits-Secrets (Pflicht)

Ersetze die Werte, die in .env.example mitkommen, bevor du die Instanz exponierst — sie sind absichtlich unsichere Platzhalter.

Datenbank

Tale betreibt zwei Postgres-Datenbanken: den operativen Speicher (db, Port 5432) hinter dem Convex-Backend und den Wissens-Korpus (knowledge-db, Port 5433), der Dokument-Chunks, Embeddings und gecrawlte Seiten hält. Beide sind ParadeDB und teilen sich DB_PASSWORD, aber sie sind unabhängig — zeig jede für sich auf externe Infrastruktur.

Die auto-konstruierte operative Form ist postgresql://tale:${DB_PASSWORD}@db:5432. Convex erwartet diese URL ohne Datenbanknamen; der Name wird aus der Instanz-Konfiguration abgeleitet. Der Wissens-Korpus lebt in tale_knowledge mit den Schemata private_knowledge und public_web; die UI unter Einstellungen > Datenresidenz schreibt eine reichere Per-Store-Konfiguration als diese rohen Variablen, behandelt in Datenresidenz.

Observability

METRICS_BEARER_TOKEN zu setzen exponiert zwei Endpoints hinter dem Token: /metrics/platform und /metrics/convex (Convex' 261 eingebaute Metriken, die jetzt auch die RAG- und Crawl-Timings tragen). Siehe Observability-Konfig für die Scrape-Konfiguration.

Provider-Secrets-Verschlüsselung

Wenn beide age-Vars unset sind, speichert Tale providers/*.secrets.json als Klartext-JSON mit Modus 0600. Erreich diesen Modus nur, wenn der Host-Storage at-rest verschlüsselt ist oder die Dateien von externem Tooling erzeugt werden (ein Kubernetes-Secret-Mount, ein Vault-Template). Einen age-Key zu rotieren bedeutet, den neuen Key anzuhängen, jeden Provider in der UI neu zu speichern, dann den alten Key zu entfernen. Siehe Secrets mit SOPS für den vollen Rotations-Walkthrough.

Die Umgebungsvariablen-Schlüsselquelle braucht keinen Deployment-Schalter: ein Anbieter kann seinen Schlüssel aus einer Umgebungsvariable statt aus einer Secrets-Datei lesen, solange die Variable mit dem reservierten Präfix TALE_PROVIDER_KEY_ benannt ist (jeder andere Name wird abgelehnt). Der Mechanismus — die Präfix-Schranke, Auflösungs-Reihenfolge, die 40-Zeichen-Grenze, die Neustart-Anforderung — ist in Anbieter dokumentiert.

Eine Token-Quelle folgt demselben Muster für das Auth-Geheimnis, das sie an den Broker sendet: Sie liest aus einem verschlüsselten token-sources/<slug>.secrets.json-Sidecar oder aus einer Umgebungsvariable, die mit dem reservierten Präfix TALE_TOKEN_SOURCE_ benannt ist (jeder andere Name wird abgelehnt, sodass das Feld nie auf ein Deployment-Geheimnis zeigen kann). Die Variable gilt pro Quelle; definier sie hier oder in deinem Secret-Manager, damit sowohl die Plattform als auch das Convex-Backend sie lesen können.

Feature-Flags

Optionale Schalter für Features, die standardmässig nicht aktiviert sind. Jeder Flag schaltet ein Feature beim Boot ein oder aus; das Umschalten braucht einen Neustart des Plattform-Containers.

RAG-Retrieval-Tuning

Optionale Stellschrauben für die Wissensdatenbank-Suche. Der In-Process-RAG-Pfad (Convex-Node-Actions) bewertet Ergebnisse mit einem Cross-Encoder neu, wenn Re-Ranking an ist. Alle tragen das RAG_-Präfix und werden von den Containern platform und convex beim Boot gelesen; nach einer Änderung führe docker compose restart platform convex aus, damit sie wirkt.

Re-Ranking ist standardmässig deaktiviert, weil es Latenz pro Query addiert und von einem externen Endpoint abhängt. Aktiviere es — indem du RAG_RERANKING_PROVIDER=api setzt und RAG_RERANKING_API_BASE_URL auf einen gehosteten Rerank-Service zeigst — wenn Retrieval-Präzision wichtiger ist als Antwortzeit. Es gibt kein In-Process-Modell zum Herunterladen oder Cachen; mit ausgeschaltetem Re-Ranking gibt die Suche das einfache zusammengeführte BM25-+-Vektor-Ranking zurück.

Sitzungen

Lass es unset, um die Standard-Sitzungsdauer zu behalten. Wenn gesetzt, läuft eine inaktive Sitzung serverseitig ab, sobald das Fenster verstrichen ist, während eine aktive sich bei jeder Anfrage weiter verschiebt. Org-Admins können das wirksame Fenster pro Organisation verkürzen — niemals über diese Obergrenze hinaus verlängern — über die Governance-Richtlinie zur Sitzungs-Leerlaufzeit; inaktive Sitzungen unter dieser Richtlinie widerruft ein Lauf, der etwa alle fünf Minuten läuft.

Versionierung

Wo das hingehört

Die Variablen hier sind die Kontaktoberfläche des Operators; die UI-Oberfläche, die die meisten von ihnen konsumiert, lebt unter Plattform-Verwaltung. Provider-Keys sind die eine Halb-und-Halb-Sache: die Keys selbst leben in providers/*.secrets.json, aber die UI unter Einstellungen > Anbieter ist, wie du sie in der Praxis hinzufügst und rotierst. Die nächste Lektüre, die sich lohnt, ist Anbieter — sie behandelt die Datei-Form, die SOPS-Modi und das Resolve-und-Failover-Verhalten.