Référence des variables d'environnement

Tale lit sa configuration depuis un unique fichier .env à la racine du dépôt. Environ une douzaine de variables sont obligatoires au premier boot ; les autres ajustent le comportement. Cette page liste chaque variable que .env.example ship, sa valeur par défaut et la surface produit qui la consomme.

Les groupes sont ordonnés selon le moment où tu en as besoin la première fois : identité de domaine, TLS, secrets, base de données, instance, observabilité, chiffrement des fournisseurs. Si une variable change de valeur, redémarre le conteneur plateforme (docker compose restart tale-platform tale-convex) pour qu'elle prenne effet.

Comment lire cette page

Chaque groupe est un tableau Nom | Défaut | Description. Les variables marquées Obligatoire doivent être définies pour que docker compose up réussisse. Les variables marquées Optionnel peuvent rester non définies ; la description nomme ce que désactiver la fonctionnalité signifie.

Le fichier .env.example ship des commentaires inline qui expliquent chaque variable dans son contexte ; cette page est la référence structurée et groupée pour le même ensemble.

Identité de domaine (obligatoire au premier boot)

Le SITE_URL doit correspondre exactement à ce que l'utilisateur tape dans le navigateur. Un slash en queue, un port manquant ou http au lieu de https cassent le callback d'auth et produisent des boucles de sign-in.

TLS

selfsigned fait tourner Caddy avec un certificat généré — le navigateur avertit, OK pour le développement. letsencrypt exige un vrai domaine et les ports 80/443 joignables depuis l'Internet public. external fait servir Caddy en HTTP brut ; un reverse proxy amont termine TLS.

Secrets de sécurité (obligatoire)

Remplace les valeurs livrées dans .env.example avant d'exposer l'instance — ce sont des espaces réservés volontairement non sûrs.

Base de données

Tale fait tourner deux bases Postgres : la base opérationnelle (db, port 5432) derrière le backend Convex, et le corpus de connaissances (knowledge-db, port 5433) qui détient les fragments de documents, les embeddings et les pages crawlées. Les deux sont ParadeDB et partagent DB_PASSWORD, mais elles sont indépendantes — pointe l'une ou l'autre vers une infrastructure externe séparément.

La forme opérationnelle auto-construite est postgresql://tale:${DB_PASSWORD}@db:5432. Convex attend cette URL sans nom de base ; le nom est dérivé de la configuration d'instance. Le corpus de connaissances vit dans tale_knowledge avec les schémas private_knowledge et public_web ; l'UI Paramètres > Résidence des données écrit une config par banque plus riche que ces variables brutes, couverte dans Résidence des données.

Observabilité

Définir METRICS_BEARER_TOKEN expose deux endpoints derrière le token : /metrics/platform et /metrics/convex (les 261 métriques intégrées de Convex, qui portent désormais aussi les timings RAG et de crawl). Voir Configuration d'observabilité pour la configuration de scrape.

Chiffrement des secrets de fournisseur

Si les deux clés age ne sont pas définies, Tale stocke providers/*.secrets.json en JSON clair en mode 0600. Atteins ce mode seulement si le disque hôte est chiffré au repos ou si les fichiers sont produits par un outillage externe (un montage de secret Kubernetes, un template Vault). Faire tourner une clé age, c'est ajouter la nouvelle clé, réenregistrer chaque fournisseur dans l'UI, puis retirer l'ancienne. Voir Secrets avec SOPS pour la marche complète de rotation.

La source de clé par variable d'environnement ne nécessite aucun commutateur de déploiement : un fournisseur peut lire sa clé depuis une variable d'environnement plutôt que depuis un fichier de secrets, tant que la variable est nommée avec le préfixe réservé TALE_PROVIDER_KEY_ (tout autre nom est rejeté). Le mécanisme — la barrière de préfixe, l'ordre de résolution, le plafond de 40 caractères, l'exigence de redémarrage — est documenté dans Fournisseurs.

Une source de jetons suit le même schéma pour le secret d'auth du courtier qu'elle lui envoie : elle lit depuis un sidecar chiffré token-sources/<slug>.secrets.json, ou depuis une variable d'environnement nommée avec le préfixe réservé TALE_TOKEN_SOURCE_ (tout autre nom est rejeté, donc le champ ne peut jamais pointer sur un secret de déploiement). La variable est par source ; définis-la ici ou dans ton gestionnaire de secrets pour que la plateforme et le backend Convex puissent tous deux la lire.

Drapeaux de fonctionnalité

Bascules optionnelles pour des fonctionnalités non activées par défaut. Chaque drapeau active ou désactive une fonctionnalité au boot ; basculer demande un redémarrage du conteneur plateforme.

Réglage du retrieval RAG

Réglages optionnels pour la recherche dans la base de connaissances. Le chemin RAG en in-process (node-actions Convex) re-note les résultats avec un cross-encoder quand le re-ranking est activé. Tous portent le préfixe RAG_ et sont lus par les conteneurs platform et convex au boot ; après un changement, lance docker compose restart platform convex pour qu'il prenne effet.

Le re-ranking est livré désactivé parce qu'il ajoute de la latence par requête et dépend d'un endpoint externe. Active-le — en réglant RAG_RERANKING_PROVIDER=api et en pointant RAG_RERANKING_API_BASE_URL vers un service de rerank hébergé — quand la précision du retrieval compte plus que le temps de réponse. Il n'y a aucun modèle en in-process à télécharger ou à mettre en cache ; le re-ranking désactivé, la recherche renvoie le classement hybride BM25 + vecteur simple.

Sessions

Laisse-le non défini pour conserver la durée de session par défaut. Si défini, une session inactive expire côté serveur une fois la fenêtre écoulée, tandis qu'une session active continue de glisser à chaque requête. Les Administrateurs d'organisation peuvent raccourcir la fenêtre effective par organisation — jamais l'allonger au-delà de ce plafond — via la politique de gouvernance du délai d'inactivité de session ; les sessions inactives sous cette politique sont révoquées par une passe qui tourne environ toutes les cinq minutes.

Versionnage

Où cela s'inscrit

Les variables ici sont la surface de contact de l'opérateur ; la surface UI qui en consomme la plupart vit sous Plateforme administration. Les clés de fournisseur sont la moitié-et-moitié : les clés elles-mêmes vivent dans providers/*.secrets.json, mais l'UI sous Paramètres > Fournisseurs est ainsi que tu les ajoutes et les fais tourner en pratique. La lecture suivante à mettre en file est Fournisseurs — elle couvre la forme fichier, les modes SOPS et le comportement de résolution et de failover.