Configuration
Les modèles YAML sont fournis avec les livrables. Les paramètres d’installation suivent l’ordre de priorité YAML, puis environnement, puis arguments de commande. init et les services permanents doivent recevoir les mêmes accès, chemins et secrets.
Fichiers et chemins
| Usage | Linux | Windows |
|---|---|---|
| Binaires Backend | /app/smartagt-backend-core/ |
C:\app\smartagt-backend-core\ |
| Binaires du Frontend service | /app/smartagt-bff-core/ |
C:\app\smartagt-bff-core\ |
| YAML Backend | /app/config/backend/smartagt-backend-core.yaml |
C:\app\config\backend\smartagt-backend-core.yaml |
| YAML du Frontend service | /app/config/bff/smartagt-bff-core.yaml |
C:\app\config\bff\smartagt-bff-core.yaml |
| Environnement Backend | /etc/smartagt/backend.env |
C:\app\config\backend\environment.json |
| Environnement du Frontend service | /etc/smartagt/bff.env |
C:\app\config\bff\environment.json |
| Raccordement S3, si retenu | /app/s3.env |
C:\app\s3.json |
| TLS du composant | /app/config/<composant>/tls/ |
C:\app\config\<composant>\tls\ |
| Données Backend | /var/lib/smartagt/backend/ |
C:\app\data\backend\ |
| Données du Frontend service | /var/lib/smartagt/bff/ |
C:\app\data\bff\ |
| Journaux Backend | /var/log/smartagt/backend/ |
C:\app\logs\backend\ |
| Journaux du Frontend service | /var/log/smartagt/bff/ |
C:\app\logs\bff\ |
| PostgreSQL 18 | Configuration /etc/postgresql/18/main/, données /var/lib/postgresql/18/main/ |
Binaires C:\app\PostgreSQL\18\bin\, données et configuration sous data\ |
Les chemins sont ceux des procédures. Adaptez-les ensemble. Les binaires sont administrés par root ou les administrateurs Windows, les comptes applicatifs écrivent uniquement dans leurs données et journaux. Les fichiers d’environnement contiennent des secrets : mode 600 sous Linux, ACL réservées sous Windows.
Paramètres initiaux
Le nom d’environnement utilise _ pour séparer les niveaux et __ pour un underscore dans un champ : BASE__URL représente base_url.
| Paramètre YAML | Variable d’environnement | Exemple |
|---|---|---|
smartagt.core.database.host |
SMARTAGT_CORE_DATABASE_HOST |
localhost pour une base sur le même serveur |
smartagt.core.database.port |
SMARTAGT_CORE_DATABASE_PORT |
5432 |
smartagt.core.database.name |
SMARTAGT_CORE_DATABASE_NAME |
smartagt ou smartagt_bff |
smartagt.core.database.user |
SMARTAGT_CORE_DATABASE_USER |
Rôle propre au composant |
smartagt.core.database.password |
SMARTAGT_CORE_DATABASE_PASSWORD |
Secret du rôle |
smartagt.http.public.host |
SMARTAGT_HTTP_PUBLIC_HOST |
Backend : 127.0.0.1 par défaut, interface du serveur pour les clients d’autres hôtes |
smartagt.http.public.port |
SMARTAGT_HTTP_PUBLIC_PORT |
Backend : 8000 |
smartagt.http.public.tls_enabled |
SMARTAGT_HTTP_PUBLIC_TLS__ENABLED |
Backend : true. HTTPS est actif par défaut, avec un certificat autosigné ; pour poser le vôtre, voir Installer vos certificats |
smartagt.http.public.certfile |
SMARTAGT_HTTP_PUBLIC_CERTFILE |
Backend : chemin du certificat serveur |
smartagt.http.public.keyfile |
SMARTAGT_HTTP_PUBLIC_KEYFILE |
Backend : chemin de la clé privée |
smartagt.http.reload |
SMARTAGT_HTTP_RELOAD |
Backend : false |
smartagt.http.internal.url |
SMARTAGT_HTTP_INTERNAL_URL |
Backend : https://127.0.0.1:8010 par défaut ; nom du nœud API ou du load balancer en multi-serveur (simple passage TCP L4, sans terminaison TLS) |
smartagt.http.server.host |
SMARTAGT_HTTP_SERVER_HOST |
Frontend service : interface d’écoute, 0.0.0.0 pour un accès direct |
smartagt.http.server.port |
SMARTAGT_HTTP_SERVER_PORT |
Frontend service : 9000 |
smartagt.http.server.tls_enabled |
SMARTAGT_HTTP_SERVER_TLS__ENABLED |
Frontend service : true. HTTPS est actif par défaut, avec un certificat autosigné ; pour poser le vôtre, voir Installer vos certificats |
smartagt.http.server.certfile |
SMARTAGT_HTTP_SERVER_CERTFILE |
Frontend service : chemin du certificat serveur |
smartagt.http.server.keyfile |
SMARTAGT_HTTP_SERVER_KEYFILE |
Frontend service : chemin de la clé privée |
smartagt.http.server.reload |
SMARTAGT_HTTP_SERVER_RELOAD |
Frontend service : false |
smartagt.http.server.workers |
SMARTAGT_HTTP_SERVER_WORKERS |
Frontend service : 1 pour le binaire compilé |
smartagt.http.backend.base_url |
SMARTAGT_HTTP_BACKEND_BASE__URL |
Frontend service : écoute Public de l’API servant au rattachement, https://localhost:8000 sur le même serveur, ou l'adresse IP du serveur si l'API écoute sur celle-ci |
smartagt.http.cors.allow_origins[0] |
SMARTAGT_HTTP_CORS_ALLOW__ORIGINS_0 |
Frontend service : origine HTTPS exacte du navigateur |
| Variable dédiée | Usage |
|---|---|
SMARTAGT_KEK |
KEK propre au composant, générée une seule fois et conservée au coffre |
SMARTAGT_DATA_DIR, SMARTAGT_LOG_DIR |
Racines de données et journaux du processus |
PGSSLMODE=verify-full |
PostgreSQL chiffré : validation TLS complète du serveur (PostgreSQL SSL) |
PGSSLROOTCERT |
PostgreSQL chiffré : CA du serveur PostgreSQL |
SMARTAGT_INTERNAL_JOIN_SECRET_FILE |
Chemin du fichier protégé contenant le secret de déploiement, côté API et côté Frontend service, quand le premier Frontend service s’exécute sans API sur son serveur |
SMARTAGT_INTERNAL_JOIN_SECRET |
Même secret fourni directement ; la variante en fichier est recommandée |
Les API, workers et Gateway partagent la KEK Backend. Le Frontend service utilise une autre KEK et un autre mot de passe PostgreSQL. La perte d’une KEK empêche de déchiffrer les données qu’elle protège. Le secret de déploiement ne figure jamais dans un fichier YAML.
Écoutes et HTTP
Le processus API sert deux écoutes, Public et Interne ; AI Gateway sert la troisième, décrite plus bas. Les ports et les clients de chaque écoute figurent dans Réseau.
| Bloc | Champs | Valeurs par défaut |
|---|---|---|
smartagt.http.public |
host, port, tls_enabled, certfile, keyfile, trusted_proxies, timeout_keep_alive |
127.0.0.1, 8000, HTTPS avec certificat autosigné, [], 5 s |
smartagt.http.internal |
url, local_enrollment_port |
https://127.0.0.1:8010, 8011 |
smartagt.http |
max_request_size_mb, max_upload_size_mb, timeout_graceful_shutdown, reload |
16 Mo, 256 Mo, 30 s ; reload réservé au développement |
smartagt.http.backend (Frontend service) |
base_url, local_enrollment_port, timeout, limits |
Adresse de rattachement, 8011, délais et pool du client vers l’API |
Les bornes de smartagt.http s’appliquent aux deux écoutes de l’API. L’écoute Interne ne demande aucun réglage de certificat ni de proxy. Elle referme une connexion inactive après 75 secondes et ferme proprement, après sa réponse, une connexion ouverte depuis plus de 5 minutes. Le Frontend service réutilise ses connexions : une négociation TLS par connexion, pas par requête. Son pool expire les connexions inactives avant ce délai ; limits.keepalive_expiry est ramené à 60 secondes au plus. Un renouvellement de certificat ou une rotation d’autorité ne coupe aucun échange en cours.
smartagt.http.internal.url est une valeur d’installation : la première API démarrée l’enregistre, puis seule la commande run.bin pki internal-url set <url> la change. Reportez ensuite la nouvelle valeur dans le YAML de chaque nœud API et redémarrez-le : un nœud dont la valeur diffère ferme son écoute Interne avec la cause internal_url_mismatch. Le Frontend service n’a rien à changer : quand l’URL enregistrée reste sans réponse, il relit l’URL courante par smartagt.http.backend.base_url, au plus toutes les cinq minutes, par un échange authentifié par son propre secret. Il n’adopte une URL que de la même installation et avec la même clé de session ; sinon il signale backend_key_changed. smartagt.http.internal.local_enrollment_port et smartagt.http.backend.local_enrollment_port gardent la même valeur.
Bases et processus
| Base | Propriétaire | Usage |
|---|---|---|
smartagt |
smartagt |
Données Platform, Gateway et état des traitements |
smartagt_vector |
smartagt |
Index documentaires, extension vector |
smartagt_bff |
smartagt_bff |
Sessions et données du Frontend service |
| Processus | Commande | Service Linux et Windows | Nom affiché sous Windows |
|---|---|---|---|
| API | run |
SmartAGT-Platform-Service |
SmartAGT Platform Service |
| Ingestion | worker --role=rag-ingestor |
smartagt-rag-ingestor-worker |
SmartAGT RAG Ingestor Worker |
| Embedding | worker --role=rag-embed |
smartagt-rag-embed-worker |
SmartAGT RAG Embed Worker |
| Planification | worker --role=scheduler |
smartagt-scheduler-worker |
SmartAGT Scheduler Worker |
| Frontend service | run |
smartagt-frontend-service |
SmartAGT Frontend Service |
| Gateway, option | gateway |
SmartAGT-AI-Gateway-Service |
SmartAGT AI Gateway Service |
Chaque commande utilise run.bin ou run.exe, le bon --config et l’environnement du composant. Sous Linux, le compte Backend est svc-smartagt-backend, celui du Frontend service svc-smartagt-bff. Les services Windows créés par les procédures d'installation utilisent SYSTEM. Leurs commandes sont regroupées dans Exploitation.
Topologie
Pour une installation répartie, fixez la liste smartagt.deployment.nodes avant l’initialisation et le premier démarrage Platform. Fournissez ce manifeste à l’identique dans le YAML de chaque nœud Backend et conservez-le pour les démarrages suivants. Chaque entrée décrit le placement des composants :
| Champ | Valeur |
|---|---|
node_id |
Identifiant stable et unique, de 1 à 40 lettres, chiffres, tirets ou underscores, commençant par une lettre ou un chiffre |
address |
Nom DNS ou adresse IP joignable entre les nœuds, sans port |
components |
Rôles présents : platform, rag-ingestor, rag-embed, scheduler, gateway ou bff pour le Frontend service |
Définissez SMARTAGT_NODE_ID dans l’environnement local de chaque nœud Backend avec son node_id. Chargez cette identité avec les autres variables du service. Le concept Stockage précise les placements possibles et la matrice des flux les connexions à autoriser.
Raccordement S3
Pour utiliser S3, définissez smartagt.mediastore.backend: s3 et renseignez endpoint_url et bucket sous smartagt.mediastore.s3. region est facultatif selon le fournisseur. S3 est obligatoire en conteneurs et possible en natif.
Les clés d'accès sont des secrets et ne figurent jamais dans le YAML : fournissez-les par l'environnement, dans SMARTAGT_MEDIASTORE_S3_ACCESS__KEY et SMARTAGT_MEDIASTORE_S3_SECRET__KEY. Le double underscore est requis : il représente celui des champs access_key et secret_key.
La procédure Configurer S3 indique les valeurs à placer dans le YAML et les variables à fournir avant init. API et workers utilisent ensuite le même raccordement. Le choix des persistances et leur placement sont expliqués dans Stockage.
Proxies et SSO
smartagt.http.public.trusted_proxies pour l’écoute Public de l’API et smartagt.http.server.trusted_proxies pour le Frontend service contiennent uniquement les IP ou CIDR des proxies qui peuvent transmettre l’adresse cliente. Ces listes décident seules des en-têtes X-Forwarded-* acceptés. Sans proxy, conservez [], jamais tout le réseau utilisateur.
Sur l’écoute Interne, le Backend reprend l’adresse de l’utilisateur transmise par le Frontend service, authentifié par son certificat : un seul en-tête X-Forwarded-For, portant une seule adresse valide. Le journal d’activité et les limiteurs voient ainsi l’adresse réelle de l’utilisateur, sans déclarer le Frontend service comme proxy de confiance.
Pour OIDC et Entra ID, le YAML Backend doit autoriser l’origine du navigateur :
smartagt:
iam:
oidc:
frontend_allowed_origins:
- "https://smartagt.example.org"
Une liste vide refuse les connexions OIDC. L’origine doit correspondre à celle du Frontend service, de ses CORS et des URL de retour déclarées auprès du fournisseur d’identité. Les écrans de configuration SSO sont décrits dans la documentation produit.
AI Gateway
Le bloc smartagt.gateway.server règle l’écoute Gateway, indépendante des écoutes de l’API sous smartagt.http :
| Champ | Valeur ou borne |
|---|---|
host, port |
Interface prévue, 8001 |
tls_enabled, certfile, keyfile |
HTTPS obligatoire : certificat autosigné par défaut, ou paire posée par Installer vos certificats |
trusted_proxies |
[] ou adresses précises du proxy Gateway |
reload, workers |
false, 1 |
max_request_size_mb |
Défaut 16, de 1 à 64 |
max_concurrent_requests |
Défaut 64, de 1 à 512 |
body_timeout_seconds |
Défaut 30, de 1 à 120 |
Les limites sous smartagt.gateway.admission portent sur la fréquence et la concurrence par clé et par titulaire. Plusieurs instances partagent l’admission en PostgreSQL ; dimensionnez leurs pools avec ceux de Platform et des workers. L’activation, les adresses clientes autorisées et les catalogues restent des réglages applicatifs.
Ports et flux · Installer vos certificats · Installer le Backend · Installer le Frontend.