Fichiers de configuration

Ce chapitre dit quels fichiers le code lit, où ils vivent et dans quel ordre ils s'appliquent. La liste des variables est dans Variables d'environnement.

Les fichiers que le code lit

Fichier	Emplacement	Lu par	Rôle
`.env`	Répertoire de lancement (racine du dépôt en développement)	`dotenvy`, au démarrage de `forge-api`	Variables de développement. Ignoré par git
`.env.example`	Racine du dépôt	Personne : c'est un modèle à copier	Liste commentée des variables, avec des valeurs à remplacer
`connectors/*.yaml`	Racine du dépôt, ou le dossier `CONNECTOR_CATALOGUE_DIR`	`CatalogueLoader` (`crates/forge-mcp/src/connector/catalogue.rs`)	Un manifeste par connecteur
`policies/chatbotaurus.cedarschema` et `policies/policies.cedar`	Dossier `policies/`, chemin relatif au répertoire de lancement	`load_cedar_policy_engine` (`crates/forge-api/src/main.rs`)	Règles d'autorisation Cedar
`crates/forge-ui/Dioxus.toml`	Crate `forge-ui`	`dx`	Réglages du serveur de développement du frontend
`crates/forge-docs/book.toml`	Crate `forge-docs`	`mdbook`	Réglages de ce livre

Le code ne lit pas de fichier .env.staging ni .env.production. Pour un autre environnement, posez les variables dans le processus.

Si policies/ est absent ou illisible depuis le répertoire de lancement, le comportement dépend de la posture. En développement déclaré, le moteur Cedar n'est pas chargé, forge-api démarre sans lui et les gardes Cedar laissent passer. En posture de production, forge-api refuse de démarrer (décision de démarrage du moteur Cedar, dans le code). Lancez le binaire depuis la racine du dépôt.

Fichiers de déploiement

Deux plans Podman existent, chacun avec son fichier Compose :

Fichier	Plan	Contenu
`podman-compose.yml`	Backend (services `forge-*`)	PostgreSQL, Valkey, Qdrant, Ollama, Authentik, OpenBao, VictoriaMetrics, VictoriaLogs, CrowdSec, voix, sauvegarde
`podman-compose.vps2.yml`	Client (services `mcp-*`)	Passerelle MCP et serveurs d'outils métier

Ces fichiers servent au développement local. En production, le déploiement installe des unités Quadlet : un fichier containers/<service>/<service>.container par service, appliqué par containers/scripts/deploy-all.sh. Voir Déploiement avec Podman.

Tapez podman-compose avec un tiret. podman compose (avec une espace) ne fournit pas de moteur Compose propre : il délègue à un outil externe qui peut manquer.

Les deux réseaux et les volumes de données sont déclarés external dans les fichiers Compose : compose ne les crée pas. Créez-les avant le premier lancement (procédure dans Déploiement avec Podman).

Configuration du backend

forge-api construit sa configuration avec ForgeConfig::from_env (crates/forge-core/src/config.rs). Créez .env à la racine du dépôt (cp .env.example .env, ou le fichier minimal ci-dessous) ; seules DATABASE_URL, REDIS_URL et JWT_SECRET sont exigées, et openssl rand -hex 32 produit un JWT_SECRET valable (voir Variables d'environnement). Exemple minimal de .env de développement, avec des gabarits à remplacer :

DATABASE_URL=postgres://<utilisateur>:<mot-de-passe>@localhost:5432/<base>
REDIS_URL=redis://localhost:6380
JWT_SECRET=<32-caracteres-aleatoires-au-minimum>
OLLAMA_BASE_URL=http://localhost:11434
QDRANT_URL=http://localhost:6334
SMTP_HOST=<serveur-smtp>
SMTP_PORT=587
SMTP_USER=<compte-smtp>
SMTP_PASSWORD=<mot-de-passe-smtp>
RUST_LOG=info,forge_api=debug

Le Valkey de podman-compose.yml est publié sur le port 6380 de l'hôte par défaut (variable REDIS_PORT) ; 6379 est le port interne du conteneur. Si vous utilisez un Redis local sur 6379, adaptez l'URL. Avec le compose de développement, l'utilisateur, le mot de passe et la base de DATABASE_URL sont ceux des variables DATABASE_USER, DATABASE_PASSWORD et DATABASE_NAME (valeurs par défaut de développement dans podman-compose.yml).

Au démarrage, forge-api imprime sur l'erreur standard dotenvy: loaded <chemin> si .env a été chargé, ou dotenvy: .env NOT loaded sinon. Si le message dit que le fichier n'a pas été chargé, le répertoire de lancement n'est pas la racine du dépôt.

Les valeurs de production ne sont pas dans le dépôt. Un script génère sur chaque hôte les fichiers d'environnement avec des permissions restreintes (script d'initialisation des secrets de l'hôte). Si BAO_ADDR est posée, OpenBao surcharge ensuite les secrets d'exécution.

Configuration du frontend

forge-ui ne lit aucun fichier à l'exécution.

Le serveur de développement est dx serve, lancé depuis crates/forge-ui. Dioxus.toml le règle pour surveiller le dossier src : une modification de code recharge la page sans redémarrer.
En web, le frontend appelle le chemin relatif /api/v1 du même domaine. Sur les cibles natives, API_URL fixe l'adresse à la compilation ; le défaut est http://localhost:3000/api/v1 (crates/forge-ui/src/config/api.rs).
Les textes de marque, les liens et les offres affichés sur le site vivent dans crates/forge-ui/src/config/site.rs. Ce fichier ne contient pas l'adresse de l'API.

Manifestes de connecteurs (`connectors/*.yaml`)

Au démarrage, forge-api charge chaque .yaml du dossier. Il remplace les ${VARIABLE:-défaut} par l'environnement, puis enregistre le connecteur. Un manifeste invalide est journalisé et ignoré, il n'arrête pas le démarrage.

Le dossier contient 195 manifestes (mesure du 2026-10-03 : ls connectors/*.yaml | wc -l). Forme d'un connecteur HTTP (modèle commenté : connectors/README.md) :

id: <identifiant>
display_name: "<nom affiché>"
base_url: "${<VARIABLE>:-<url-par-defaut>}"
auth:
  type: bearer            # none | bearer | api_key | basic | query_token | jwt_exchange | oauth2 | login_token | checksum | json_rpc_session
  token_env: <VARIABLE>
compliance:
  data_residency: eu
  self_hosted: true
  gdpr_compliant: true
  license: "<licence>"
timeout_ms: 30000
tools:
  - name: <outil>
    description: "<description>"
    method: GET
    path: "/chemin/{parametre}"
    param_location: path
    input_schema:
      type: object
      properties: {}

Le manifeste d'Odoo suit une autre forme : type: odoo et les champs url, database, username, api_key, lus dans ODOO_URL, ODOO_DATABASE, ODOO_USERNAME et ODOO_API_KEY (connectors/odoo.yaml). La clé d'API y est marquée obligatoire (${ODOO_API_KEY:?...}), mais le chargeur la remplace par une chaîne vide si elle est absente : le manifeste se charge, et les appels d'Odoo échouent faute d'identifiants.

Le registre refuse un connecteur dont gdpr_compliant vaut false ou dont la résidence des données n'est pas dans l'UE ou auto-hébergée. Le journal le dit : connector rejected by registry.

Les secrets ne sont jamais écrits dans les manifestes : ils viennent de l'environnement.

Appliquer un changement

Backend : redémarrez forge-api. Il ne relit pas la configuration à chaud. En développement sous Windows, scripts/dev/watch-forge-api.ps1 reconstruit et relance le binaire après une modification de code.
Frontend : rien à faire en développement, dx serve recharge.
Services Podman : en développement, podman-compose -f podman-compose.yml up -d applique la nouvelle définition ; --force-recreate recrée les conteneurs. En production, l'hôte tire lui-même la branche principale (minuteur systemd) : voir « Déploiement tiré par l'hôte » dans Déploiement avec Podman.

Voir aussi

Variables d'environnement — la liste des variables que ces fichiers alimentent
Installation de Chatbotaurus — première configuration de l'environnement de développement, pas à pas
Déploiement avec Podman — fichiers Compose, unités Quadlet et déploiement tiré par l'hôte
Conception des connecteurs MCP — tous les champs d'un manifeste et le contrôle de conformité
Problèmes connus — configuration du frontend ignorée, connecteur rejeté au démarrage

Raccourcis clavier