Umgebungsreferenz

Die Umgebungsreferenz katalogisiert jede Variable, die Tale beim Container-Start liest. Operatoren konsultieren diese Seite, wenn ein Knopf geändert werden muss — eine Domain, ein TLS-Modus, ein SSO-Mandant — und nochmal, wenn etwas, was die Laufzeit erwartete zu finden, nicht da ist. Die Wahrheitsquelle ist .env.example und die Per-Service-Env-Loader; die Tabellen unten sind nach Oberfläche gruppiert, sodass die Variablen, die eine Sorge regieren, nahe beieinander bleiben.

Jede Variable lebt in .env im Projekt-Wurzelverzeichnis. tale init versorgt die Datei mit vernünftigen Voreinstellungen; Produktions-Deployments überschreiben Domain-, TLS- und Datenbankwerte, und die meisten Installationen rühren nichts anderes an.

Wie diese Seite zu lesen ist

Variablen sind danach gruppiert, was sie kontrollieren — Domain, TLS, Secrets, Datenbank, Monitoring, SSO, vertrauenswürdige HTTP-Kopfzeilen, Aufbewahrung, Deployment. Jede Gruppe öffnet mit ein bis zwei Sätzen, die benennen, was die Gruppe regiert, dann folgt eine Name | Voreinstellung | Beschreibung-Tabelle. Variablen ohne Voreinstellung sind voreingestellt ungesetzt; fehlende erforderliche Variablen führen dazu, dass der Container den Start mit der auf der Fehlersuche-Seite genannten Meldung verweigert.

Änderungen greifen beim Container-Start, also verlangt das Bearbeiten von .env ein tale deploy (Produktion) oder ein tale start (lokal). Ein laufender Stack liest .env nie erneut.

Domain

HOST ist der Hostname, den Docker für internes Routing und E-Mail nutzt; SITE_URL ist die vollständige URL, die Nutzer in den Browser tippen, einschließlich eines nicht standardmäßigen Ports. BASE_PATH wird nur gesetzt, wenn ein vorgelagerter Proxy Tale unter einem Subpath ausliefert.

SITE_URL muss der URL entsprechen, die Nutzer tatsächlich erreichen. Wenn dein Reverse-Proxy auf :8443 lauscht, nimm ihn auf: SITE_URL=https://example.com:8443. Der Proxy nutzt diesen Wert, um OAuth-Callback-URLs und den Passwort-Reset-Link zu bauen, also bricht eine Diskrepanz beide Abläufe still.

TLS

Drei Modi decken die Zertifikatsoptionen ab. selfsigned ist die lokale Voreinstellung; letsencrypt ist die Produktions-Voreinstellung; external ist für Deployments, in denen ein vorgelagerter Proxy TLS bereits terminiert.

Selbstsignierte Zertifikate lösen eine Browser-Warnung aus, bis du auf dem Host docker exec tale-proxy caddy trust fährst. Let's Encrypt braucht die Ports 80 und 443 vom öffentlichen Internet erreichbar für die ACME-Challenge. Der externe Modus fährt Caddy nur auf HTTP; der vorgelagerte Proxy behandelt TLS und leitet WebSocket-Upgrades für den Convex-Realtime-Kanal weiter.

Security-Secrets

Das sind die Secrets, ohne die die Plattform den Start verweigert. tale init erzeugt jedes einzelne; das Rotieren macht alles ungültig, was zuvor mit dem alten Wert verschlüsselt wurde.

Die Datei .env.example liefert Platzhalter-Secrets aus. Ersetze jeden einzelnen, bevor du den Stack startest, auch für lokale Entwicklung; die Platzhalter sind öffentlich auf GitHub, und ein Angreifer, der die Instanz erreicht, kann mit ihnen Auth-Tokens fälschen. Die SOPS-Modi — verschlüsselt, Klartext, Schlüssel-Rotation — werden unter Anbieter behandelt.

Datenbank

DB_PASSWORD ist das Passwort für den gebündelten Postgres-Container. Die Override-Variablen zählen nur, wenn Tale auf eine externe Postgres-Instanz ausgerichtet wird — das vollständige Muster steht unter Produktions-Deployment.

Ohne POSTGRES_URL baut Tale die URL als postgresql://tale:${DB_PASSWORD}@db:5432. Die beiden service-spezifischen URLs überschreiben die Basis-URL nur für den benannten Service, was Read-Replikas und Per-Service-Routing möglich macht.

Fehler-Tracking

Tales Fehler-Reporting spricht das Sentry-DSN-Format. Selbst gehostetes Sentry, GlitchTip und Bugsink akzeptieren alle dieselbe DSN-Form, also funktioniert jedes davon als Drop-in-Ersatz. Lass die Variable ungesetzt, um Fehler nur in Docker-Logs zu halten.

Monitoring

Jeder Dienst exponiert einen Prometheus-Textformat-Endpunkt /metrics im internen Docker-Netzwerk. Um sie durch den Proxy für ein externes Prometheus zu exponieren, setze ein Bearer-Token:

Die vollständige Endpunkt-Liste und eine Beispiel-Prometheus-Scrape-Konfiguration stehen unter Betrieb.

Service-URLs

Docker Compose verdrahtet Service-zu-Service-Verkehr automatisch, also müssen die URLs unten selten überschrieben werden. Die Variablen existieren für eigene Topologien — RAG auf einem separaten Host laufen lassen, den Crawler horizontal skalieren und so weiter.

Docker

Diese kontrollieren, wie docker compose und tale deploy Images ziehen.

Microsoft Entra SSO

Diese drei Variablen zählen nur, wenn SSO über .env statt über den Bildschirm Einstellungen > Integrationen in der App konfiguriert wird. Die meisten Operatoren nutzen die UI; die Env-Var-Form ist nützlich für Infrastructure-as-Code-Setups, bei denen die SSO-Konfiguration im selben Repository wie .env lebt.

Der vollständige SSO-Ablauf steht unter Authentifizierung.

Vertrauenswürdige HTTP-Kopfzeilen

Für Deployments hinter einem authentifizierenden Reverse-Proxy — Authelia, Authentik, oauth2-proxy — liest Tale die Identität des Nutzers aus HTTP-Kopfzeilen, die der Proxy setzt, und versorgt dann bei der ersten Anfrage ein Konto.

Aktiviere vertrauenswürdige Kopfzeilen nur, wenn der vorgelagerte Proxy diese Kopfzeilen von externen Anfragen entfernt. Wenn externe Clients die Kopfzeilen direkt setzen können, können sie jeden Nutzer imitieren. Die vollständige Konfigurations-Anleitung steht unter Authentifizierung.

Aufbewahrung

Die Aufbewahrungsgrenzen für jede Datenkategorie kommen aus JSON-Dateien unter TALE_CONFIG_DIR/retention/. Die Umgebungsvariablen unten verschärfen diese Grenzen — sie können nicht ausweiten, was die Datei deklariert. Das vollständige geschichtete Modell steht unter Aufbewahrung.

Eine Handvoll Variablen berühren den Audit-Log-Boden und den Legal-Hold-Ablauf statt Per-Kategorie-Grenzen:

Die Per-Kategorie-_MIN/_MAX-Overrides sind vollständig unter Aufbewahrung — Umgebungsvariablen gelistet.

KI-Anbieter

Anbieter-API-Schlüssel, Basis-URLs und Modell-Definitionen sind keine Umgebungsvariablen — sie leben in JSON-Dateien unter TALE_CONFIG_DIR/providers/. Das On-Disk-Schema, die SOPS-Verschlüsselungsmodi und die Regeln für das Weiterleiten anbieterspezifischer Optionen stehen unter Anbieter.

Wo das einsetzt

Die Umgebungsreferenz ist die Operator-API zu Tale. Alles, was die Laufzeit braucht und was nicht im Code mitgeliefert oder über die UI gesetzt wird, lebt in einer der Variablen oben, und die meisten haben vernünftige Voreinstellungen — die produktionsreifen Installationsseiten überschreiben nur Domain, TLS, Secrets und die Datenbank. Die UI-Gegenstücke der in der App auftauchenden Werte leben unter Einstellungen > Governance, Einstellungen > Anbieter und Einstellungen > Branding; greife zu Governance, Anbieter und Branding für die Per-Funktion-Referenz.

Wenn die Laufzeit eine Variable erwartet, die nicht da ist, sagt das Boot-Log das auf stderr. Fehlersuche katalogisiert die häufigsten Umgebungs-Fehlkonfigurationen; die Seite Release-Notes-Format deckt ab, wie Deprecations landen.