Aller au contenu

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.