La configuration de Cortex vit dans le fichier .env à la racine du dépôt, que l’on crée en copiant .env.example. Ce dernier est la référence : chaque variable y est commentée. Compose lit le fichier .env de l’hôte à chaque exécution; un contrôle automatique vérifie seulement que chaque variable utilisée par Compose y est déclarée avec la même valeur par défaut. Cette page reprend les variables utiles à un administrateur, par thème. Les valeurs par défaut sont celles de .env.example.
Où une valeur prend effet
Docker Compose lit .env sur l’hôte. Un conteneur ne reçoit une variable que si docker-compose.yml la liste dans son bloc environment:. Les variables de la passerelle présentées ici le sont, sauf celles dont le rôle commence par « Hôte seulement » : pour celles-là, modifier .env ne change rien dans les conteneurs, qui gardent la valeur par défaut du code. Elles ne servent qu’à un processus lancé directement sur l’hôte (pnpm gateway:dev, une commande d’administration), ou une fois ajoutées au bloc environment: du service. Le moteur IA n’a pas de service Compose : on le lance avec docker run -e …, et ses variables (CONTEXT_SIGNING_PUBLIC_KEY, DLP2_*, RAG_EMBEDDING_*) se passent à son conteneur, pas par .env. Les commandes pnpm --filter gateway … (tenant:provision, audit:verify…) ne lisent pas .env : donnez-leur les valeurs en ligne ou exportez-les dans le shell. Seul le raccourci pnpm migration:run, à la racine du dépôt, lit .env. Après une modification, relancez le service concerné avec docker compose up -d <service>, qui recrée le conteneur et relit les valeurs.
Base de données et clés
Variable
Rôle
Défaut
DATABASE_URL
Identité d’exécution de la passerelle (rôle cortex_gateway). Obligatoire pour une base externe.
vide : Compose construit l’URL de la base fournie
MIGRATION_DATABASE_URL
Hôte seulement. Identité propriétaire (cortex_owner) pour les migrations et les commandes d’administration.
absente : repli sur DATABASE_URL
KMS_LOCAL_KEK
Clé de chiffrement des clés (32 octets en base64). Obligatoire; la même valeur pour la passerelle et pour les commandes qui la chargent (tenant:provision, user:create, destination:create, tenant:erase, audit:verify; migration:run n’en a pas besoin).
vide : Compose substitue une clé de développement publiée
Locataire et authentification
Variable
Rôle
Défaut
AUTH_TENANT_SLUG
Locataire servi par ce déploiement. La passerelle refuse de démarrer sans lui.
cortex
AUTH_LOCAL_ENABLED
Comptes locaux (courriel et mot de passe). Seule la valeur exacte true les active. Refus de démarrer si false sans OIDC ni SAML.
true
GATEWAY_PUBLIC_URL
Origine publique de la passerelle, dont dérivent les adresses de retour SSO. Derrière le proxy web : l’origine web suivie de /api/gateway.
OIDC. L’URL de l’émetteur l’active; l’identifiant et le secret deviennent alors obligatoires.
vides
SAML_IDP_SSO_URL, SAML_IDP_CERT
SAML. L’URL l’active; le certificat devient alors obligatoire.
vides
SAML_SP_ENTITY_ID
Identifiant du fournisseur de service, identique à celui enregistré chez le fournisseur d’identité.
cortex-gateway
SESSION_TTL_HOURS
Hôte seulement. Durée d’une session, en heures (nombre positif).
8
Langue
Variable
Rôle
Défaut
DEFAULT_LOCALE
Langue de l’interface : en ou fr-CA (toute autre valeur donne en). C’est aussi la langue par défaut d’un locataire créé par tenant:provision, si la variable est exportée dans le shell ou si --locale est passé.
en
Moteur IA
Variable
Rôle
Défaut
AI_ENGINE_ENABLED
Active l’appel au moteur. Désactivé, la passerelle ne l’appelle jamais.
false
AI_ENGINE_URL
Origine du moteur (schéma, hôte, port; sans chemin). Obligatoire si activé.
vide
CONTEXT_SIGNING_PRIVATE_KEY
Clé privée Ed25519 (PKCS#8 DER en base64) qui signe l’en-tête envoyé au moteur. Obligatoire si activé.
vide
CONTEXT_SIGNING_PUBLIC_KEY
Hôte seulement. Clé publique correspondante, lue par le moteur.
vide
AI_ENGINE_DLP_TIMEOUT_MS
Délai d’un appel de détection DLP 1.5. Passé ce délai, la requête continue avec le DLP 1 seul.
3000
AI_ENGINE_DLP2_TIMEOUT_MS
Délai d’un appel de détection par modèle local (DLP 2), avec la même dégradation.
20000
AI_ENGINE_RAG_TIMEOUT_MS
Délai d’une extraction de document ou d’un lot d’embeddings.
120000
DLP2_BACKEND_URL, DLP2_MODEL
Hôte seulement. Serveur compatible OpenAI (avec son préfixe /v1) et modèle de la détection DLP 2; à définir ensemble.
vides
Base de connaissances
La base de connaissances exige le moteur IA et un serveur d’embeddings. Si le moteur est désactivé dans la configuration, les téléversements sont refusés; ils attendent dans la file seulement tant que le moteur ne répond pas ou qu’aucun modèle d’embedding n’est déclaré.
Variable
Rôle
Défaut
RAG_MAX_DOCUMENT_BYTES
Taille maximale d’un document, en octets (1024 à 33554432).
10485760
RAG_MAX_DOCUMENTS
Nombre maximal de documents par locataire, tous états confondus.
1000
RAG_TOP_K
Nombre maximal de passages injectés dans un tour (1 à 20).
5
RAG_MIN_SIMILARITY
Similarité minimale d’un passage (0 à 1); dépend du modèle.
0.3
RAG_INGEST_INTERVAL_MS
Cadence du traitement des documents. 0 le désactive : les documents restent « Téléversé ».
5000
RAG_INGEST_TIMEOUT_MS
Au-delà, un document bloqué en traitement est repris.
600000
RAG_EMBEDDING_DIM
Hôte seulement. Largeur des vecteurs, figée une fois les migrations exécutées.
1024
RAG_EMBEDDING_BACKEND_URL, RAG_EMBEDDING_MODEL
Hôte seulement. Serveur d’embeddings compatible OpenAI (avec /v1) et modèle; à définir ensemble. Ce serveur reçoit le texte des documents en clair.
vides
Cache, recherche web, coûts et acheminement
Variable
Rôle
Défaut
CACHE_ENABLED
Active le cache de réponses exactes (le DLP s’applique toujours).
false
CACHE_BACKEND
memory ou redis.
memory
CACHE_TTL_SECONDS
Durée maximale d’une entrée; la rétention du locataire la plafonne aussi.
3600
CACHE_MAX_ENTRIES
Nombre maximal d’entrées du cache en mémoire.
1000
CACHE_EXCLUDED_ROLES
Rôles exclus du cache, séparés par des virgules.
vide
REDIS_URL
Lue seulement avec redis, par exemple redis://redis:6379.
vide
WEB_SEARCH_ENABLED
Active la recherche web; les quatre suivantes deviennent alors déterminantes.
false
WEB_SEARCH_ENGINE
searxng ou brave.
searxng
WEB_SEARCH_BASE_URL
Adresse du moteur, que le conteneur de la passerelle doit pouvoir joindre. Obligatoire si activé.
vide
WEB_SEARCH_API_KEY
Clé du moteur; obligatoire avec brave.
vide
WEB_SEARCH_TIMEOUT_MS
Délai d’une recherche (1 à 120000).
10000
FINOPS_LOCAL_COST_PER_MTOK
Tarif forfaitaire par million de jetons des destinations locales.
Limites par défaut (requêtes et jetons par minute) des clés virtuelles sans limite propre.
vides : aucune limite
ROUTING_RETRY_MAX_ATTEMPTS
Tentatives par destination, la première comprise (1 à 5).
2
ROUTING_RETRY_BASE_MS
Délai de base avant une reprise, doublé à chaque essai (0 à 5000).
200
Rétention
Variable
Rôle
Défaut
RETENTION_PURGE_INTERVAL_MS
Hôte seulement. Intervalle entre deux purges planifiées. Une valeur nulle, négative ou non numérique ne planifie aucune purge, sans message.
3600000
Pour toutes les autres variables (ports, journalisation, METRICS_TOKEN, délais des fournisseurs, fenêtre du réécrivain DLP, premier administrateur), consultez .env.example dans le dépôt.
