Configuration
Les modèles YAML sont fournis avec les livrables. Un paramètre se pose dans le YAML, dans l’environnement ou en argument de commande (--smartagt.http.public.port=8000) : l’environnement remplace le YAML, et l’argument de commande remplace les deux. 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\ |
| Modèles locaux, sous les données Backend | /var/lib/smartagt/backend/models/huggingface/ |
C:\app\data\backend\models\huggingface\ |
| 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. Les variables SMARTAGT_… de la configuration acceptent aussi une variante _FILE : elle lit sa valeur dans le fichier indiqué et l’emporte sur la variable directe. SMARTAGT_KEK, SMARTAGT_NODE_ID, SMARTAGT_CLUSTER_ENABLED, SMARTAGT_DATA_DIR et SMARTAGT_LOG_DIR font exception : fournissez-les directement.
| 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.certfile |
SMARTAGT_HTTP_PUBLIC_CERTFILE |
Backend : chemin du certificat serveur. HTTPS est toujours actif, avec un certificat autosigné par défaut ; pour poser le vôtre, voir Installer vos certificats |
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 par défaut pour un accès direct, ou l’adresse IP d’une interface précise |
smartagt.http.server.port |
SMARTAGT_HTTP_SERVER_PORT |
Frontend service : 9000 |
smartagt.http.server.certfile |
SMARTAGT_HTTP_SERVER_CERTFILE |
Frontend service : chemin du certificat serveur. HTTPS est toujours actif, avec un certificat autosigné par défaut ; pour poser le vôtre, voir Installer vos certificats |
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.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, 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.server (Frontend service) |
host, port, certfile, keyfile, trusted_proxies, timeout_keep_alive, timeout_graceful_shutdown, reload |
0.0.0.0, 9000, HTTPS avec certificat autosigné en serveur unique, [], 5 s, 15 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, l'origine de l'URL publique est admise automatiquement. Le YAML Backend autorise les origines supplémentaires du navigateur :
smartagt:
iam:
oidc:
frontend_allowed_origins:
- "https://smartagt.example.org"
L'origine doit correspondre à l'adresse utilisée dans le navigateur et aux URL de retour déclarées auprès du fournisseur d'identité. La liste CORS du Frontend se configure séparément : CORS. 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 |
0.0.0.0 par défaut ou l’adresse IP d’une interface précise, 8001 |
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 |
timeout_keep_alive |
Défaut 5 s |
reload, workers |
false, 1 (valeur exigée par le binaire compilé) |
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 |
smartagt.gateway.admission.deadline_seconds fixe l’échéance d’un appel admis : 300 s par défaut, de 1 à 1 800. Les limites d’une clé AI Gateway se saisissent dans l’application et se répartissent entre les nœuds dont le service AI Gateway est en marche : démarrez un seul service AI Gateway par nœud, sous son SMARTAGT_NODE_ID. Chaque instance ouvre son propre pool PostgreSQL : dimensionnez-le 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.