Installer le Frontend
Cette procédure installe le Frontend en quatre étapes.
- Package et YAMLDépôt et configuration
- KEKClé de chiffrement de clés
- InitialisationSchéma et rattachement
- ServiceFrontend
Prérequis
- Backend installé et lancé : Installer le Backend.
- Base
smartagt_bffcréée : Préparer les bases. - Package Frontend copié sur le serveur.
- Nom DNS d'accès des postes, par exemple
smartagt.example.test, résolu vers ce serveur.
- Backend installé et lancé sur ses nœuds, secret de déploiement dans le coffre : Installer le Backend.
- Base
smartagt_bffcréée : Préparer les bases. - Package Frontend copié sur chaque nœud Frontend.
- Pour chaque nœud Frontend, un certificat et sa clé, au nom sous lequel le reverse proxy vérifie les nœuds : SmartAGT ne génère ce certificat qu'en serveur unique.
Procédure
1. Déposer le package et créer la configuration
sudo mkdir -p /app/config/bff
sudo tar -xzf <package Frontend> -C /app
sudoedit /app/config/bff/smartagt-bff-core.yaml
New-Item -ItemType Directory -Force C:\app\config\bff | Out-Null
Expand-Archive <package Frontend> C:\app\smartagt-bff-core
notepad C:\app\config\bff\smartagt-bff-core.yaml
Donnez au fichier smartagt-bff-core.yaml le contenu de votre scénario :
smartagt:
core:
data_dir: /var/lib/smartagt/bff
log_dir: /var/log/smartagt/bff
database:
host: localhost
port: 5432
name: smartagt_bff
user: smartagt_bff
http:
cors:
allow_origins:
- "https://smartagt.example.test:9000" # adresse saisie par les postes
smartagt:
core:
data_dir: C:/app/data/bff
log_dir: C:/app/logs/bff
database:
host: localhost
port: 5432
name: smartagt_bff
user: smartagt_bff
http:
cors:
allow_origins:
- "https://smartagt.example.test:9000" # adresse saisie par les postes
Dans cette configuration de base, le Frontend s'exécute avec :
- PostgreSQL sur le même serveur, joint par
localhost; - l'interface web sur le port
9000, à ouvrir en entrée sur le pare-feu du serveur ; - la connexion admise depuis l'origine déclarée dans
allow_origins, à reprendre exactement de la barre d'adresse des postes, protocole, nom et port compris : CORS ; - un certificat généré par SmartAGT pour ce port ;
- l'API Publique jointe sur
https://localhost:8000.
smartagt:
core:
data_dir: /var/lib/smartagt/bff
log_dir: /var/log/smartagt/bff
database:
host: postgres.example.test # nom porté par le certificat du serveur
port: 5432
name: smartagt_bff
user: smartagt_bff
sslmode: verify-full # chiffrement imposé, nom du serveur vérifié
sslrootcert: /app/cert/postgresql-ca.crt # autorité du certificat PostgreSQL, facultative si elle est dans le magasin du système
http:
server:
certfile: /app/config/bff/tls/server.crt # certificat présenté sur le port 9000
keyfile: /app/config/bff/tls/server.key # clé privée de ce certificat
trusted_proxies: [] # adresses de votre reverse proxy
cors:
allow_origins:
- "https://smartagt.example.test:9000" # adresse saisie par les postes
backend:
base_url: https://<adresse IP du serveur>:8000 # API Publique du Backend : même adresse que son http.public.host
smartagt:
core:
data_dir: C:/app/data/bff
log_dir: C:/app/logs/bff
database:
host: postgres.example.test # nom porté par le certificat du serveur
port: 5432
name: smartagt_bff
user: smartagt_bff
sslmode: verify-full # chiffrement imposé, nom du serveur vérifié
sslrootcert: C:/app/cert/postgresql-ca.crt # autorité du certificat PostgreSQL, facultative si elle est dans le magasin du système
http:
server:
certfile: C:/app/config/bff/tls/server.crt # certificat présenté sur le port 9000
keyfile: C:/app/config/bff/tls/server.key # clé privée de ce certificat
trusted_proxies: [] # adresses de votre reverse proxy
cors:
allow_origins:
- "https://smartagt.example.test:9000" # adresse saisie par les postes
backend:
base_url: https://<adresse IP du serveur>:8000 # API Publique du Backend : même adresse que son http.public.host
Pour cette configuration :
- déposez le certificat et sa clé : Installer vos certificats ;
- placez l'autorité de PostgreSQL et préparez le serveur : PostgreSQL SSL ;
- déclarez dans
allow_originsl'adresse saisie par les postes, celle du reverse proxy le cas échéant : CORS ; - avec un reverse proxy, déclarez ses adresses dans
trusted_proxies; - pour un Frontend sur un autre serveur que le Backend, suivez les cas particuliers.
Résultat attendu : le package est extrait et smartagt-bff-core.yaml est en place.
Sur chaque nœud Frontend :
sudo mkdir -p /app/config/bff/tls
sudo tar -xzf <package Frontend> -C /app
sudo cp server.crt server.key /app/config/bff/tls/
sudoedit /app/config/bff/smartagt-bff-core.yaml
New-Item -ItemType Directory -Force C:\app\config\bff\tls | Out-Null
Expand-Archive <package Frontend> C:\app\smartagt-bff-core
Copy-Item server.crt, server.key C:\app\config\bff\tls\
notepad C:\app\config\bff\smartagt-bff-core.yaml
Donnez au fichier smartagt-bff-core.yaml le même contenu sur tous les nœuds Frontend :
smartagt:
core:
data_dir: /var/lib/smartagt/bff
log_dir: /var/log/smartagt/bff
database:
host: postgres.example.test # adresse virtuelle de PostgreSQL
port: 5432
name: smartagt_bff
user: smartagt_bff
http:
server:
certfile: /app/config/bff/tls/server.crt # certificat de ce nœud
keyfile: /app/config/bff/tls/server.key # clé privée de ce certificat
backend:
base_url: https://platform-1.example.test:8000 # API Publique d'un nœud Platform, pour le rattachement
smartagt:
core:
data_dir: C:/app/data/bff
log_dir: C:/app/logs/bff
database:
host: postgres.example.test # adresse virtuelle de PostgreSQL
port: 5432
name: smartagt_bff
user: smartagt_bff
http:
server:
certfile: C:/app/config/bff/tls/server.crt # certificat de ce nœud
keyfile: C:/app/config/bff/tls/server.key # clé privée de ce certificat
backend:
base_url: https://platform-1.example.test:8000 # API Publique d'un nœud Platform, pour le rattachement
Dans cette configuration :
- chaque nœud présente son propre certificat sur le port
9000 base_urlsert au seul rattachement, le trafic passe ensuite par le lien interne8010- le reverse proxy se déclare après l'installation : Configurer un reverse proxy
Résultat attendu : sur chaque nœud Frontend, le package est extrait, le certificat et smartagt-bff-core.yaml sont en place.
2. Générer la clé de chiffrement de clés (KEK)
Conservez la KEK dans votre coffre : sans elle, les secrets stockés en base sont illisibles.
Générez la KEK du Frontend une seule fois, sur un nœud Frontend. Conservez-la dans votre coffre : tous les nœuds Frontend la reprennent, et sans elle les secrets stockés en base sont illisibles.
sudo /app/smartagt-bff-core/run.bin generate-kek
Une fois la KEK enregistrée dans le coffre, effacez l'écran avec clear.
C:\app\smartagt-bff-core\run.exe generate-kek
Une fois la KEK enregistrée dans le coffre, effacez l'écran avec Clear-Host.
3. Initialiser
Cette opération prépare le Frontend : elle crée les tables, initialise le chiffrement, puis rattache le Frontend à l'API du Backend.
read -rsp 'Mot de passe du rôle smartagt_bff : ' SMARTAGT_CORE_DATABASE_PASSWORD; echo
read -rsp 'KEK : ' SMARTAGT_KEK; echo
export SMARTAGT_CORE_DATABASE_PASSWORD SMARTAGT_KEK
cd /app/smartagt-bff-core
sudo --preserve-env=SMARTAGT_CORE_DATABASE_PASSWORD,SMARTAGT_KEK ./run.bin init --config /app/config/bff/smartagt-bff-core.yaml
$env:SMARTAGT_CORE_DATABASE_PASSWORD = [Net.NetworkCredential]::new('', (Read-Host 'Mot de passe du rôle smartagt_bff' -AsSecureString)).Password
$env:SMARTAGT_KEK = [Net.NetworkCredential]::new('', (Read-Host 'KEK' -AsSecureString)).Password
Set-Location C:\app\smartagt-bff-core
.\run.exe init --config C:\app\config\bff\smartagt-bff-core.yaml
Résultat attendu :
- initialisation exécutée sans erreur (code
0) ; - Frontend rattaché à l'API, sans avertissement.
Sur le premier nœud Frontend seulement. Cette opération prépare le Frontend : elle crée les tables, initialise le chiffrement, puis rattache le Frontend à l'API par le secret de déploiement.
read -rsp 'Mot de passe du rôle smartagt_bff : ' SMARTAGT_CORE_DATABASE_PASSWORD; echo
read -rsp 'KEK : ' SMARTAGT_KEK; echo
read -rsp 'Secret de déploiement : ' SMARTAGT_INTERNAL_JOIN_SECRET; echo
export SMARTAGT_CORE_DATABASE_PASSWORD SMARTAGT_KEK SMARTAGT_INTERNAL_JOIN_SECRET
cd /app/smartagt-bff-core
sudo --preserve-env=SMARTAGT_CORE_DATABASE_PASSWORD,SMARTAGT_KEK,SMARTAGT_INTERNAL_JOIN_SECRET ./run.bin init --config /app/config/bff/smartagt-bff-core.yaml
$env:SMARTAGT_CORE_DATABASE_PASSWORD = [Net.NetworkCredential]::new('', (Read-Host 'Mot de passe du rôle smartagt_bff' -AsSecureString)).Password
$env:SMARTAGT_KEK = [Net.NetworkCredential]::new('', (Read-Host 'KEK' -AsSecureString)).Password
$env:SMARTAGT_INTERNAL_JOIN_SECRET = [Net.NetworkCredential]::new('', (Read-Host 'Secret de déploiement' -AsSecureString)).Password
Set-Location C:\app\smartagt-bff-core
.\run.exe init --config C:\app\config\bff\smartagt-bff-core.yaml
Résultat attendu :
- initialisation exécutée sans erreur (code
0) - Frontend rattaché à l'API, sans avertissement
Les autres nœuds Frontend ne lancent pas init : ils lisent dans la base l'identité commune au démarrage de leur service.
4. Créer et démarrer le service
Le Frontend tourne comme service et démarre avec le serveur. Il reçoit le mot de passe et la KEK par son propre environnement.
Créez le compte du service et le fichier de ses secrets :
sudo useradd --system --no-create-home --shell /usr/sbin/nologin svc-smartagt-bff
sudo install -d /etc/smartagt
sudo install -m 600 /dev/null /etc/smartagt/bff.env
sudoedit /etc/smartagt/bff.env
SMARTAGT_CORE_DATABASE_PASSWORD=<mot de passe du rôle smartagt_bff>
SMARTAGT_KEK=<KEK du Frontend>
Créez l'unité du Frontend, /etc/systemd/system/smartagt-frontend-service.service :
[Unit]
Description=SmartAGT Frontend
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-bff
WorkingDirectory=/app/smartagt-bff-core
EnvironmentFile=/etc/smartagt/bff.env
ExecStart=/app/smartagt-bff-core/run.bin run --config /app/config/bff/smartagt-bff-core.yaml
StateDirectory=smartagt/bff
LogsDirectory=smartagt/bff
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
Une fois l'unité créée, lancez le service :
sudo systemctl daemon-reload
sudo systemctl enable --now smartagt-frontend-service
Le service se crée avec les commandes de Windows.
$password = [Net.NetworkCredential]::new('', (Read-Host 'Mot de passe du rôle smartagt_bff' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'KEK du Frontend' -AsSecureString)).Password
$name = 'smartagt-frontend-service'
New-Service -Name $name -DisplayName 'SmartAGT Frontend Service' -Description 'Interface web de SmartAGT.' -BinaryPathName '"C:\app\smartagt-bff-core\run.exe" run --config C:\app\config\bff\smartagt-bff-core.yaml' -StartupType Automatic | Out-Null
Set-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Services\$name" -Name Environment -Type MultiString -Value "SMARTAGT_CORE_DATABASE_PASSWORD=$password", "SMARTAGT_KEK=$kek"
sc.exe failure $name reset= 86400 actions= restart/10000 | Out-Null
sc.exe failureflag $name 1 | Out-Null
Start-Service $name
Fermez ensuite la console.
Mode alternatif : NSSM héberge run.exe comme service. Installez nssm.exe 64 bits dans le PATH.
$password = [Net.NetworkCredential]::new('', (Read-Host 'Mot de passe du rôle smartagt_bff' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'KEK du Frontend' -AsSecureString)).Password
$name = 'smartagt-frontend-service'
nssm install $name C:\app\smartagt-bff-core\run.exe
nssm set $name DisplayName 'SmartAGT Frontend Service'
nssm set $name Description 'Interface web de SmartAGT.'
nssm set $name AppParameters 'run --config C:\app\config\bff\smartagt-bff-core.yaml'
nssm set $name AppDirectory C:\app\smartagt-bff-core
nssm set $name AppEnvironmentExtra "SMARTAGT_CORE_DATABASE_PASSWORD=$password" "SMARTAGT_KEK=$kek"
nssm start $name
Fermez ensuite la console.
Résultat attendu : la page de connexion s'affiche sur https://smartagt.example.test:9000.
Remarque
Le navigateur signale le certificat généré par SmartAGT : acceptez l'alerte pour cette seule adresse, ou posez votre certificat avec Installer vos certificats.
Sur chaque nœud Frontend, le service reçoit le mot de passe, la KEK et le secret de déploiement par son propre environnement.
Créez le compte du service, donnez-lui la clé du certificat, puis créez le fichier de ses secrets :
sudo useradd --system --no-create-home --shell /usr/sbin/nologin svc-smartagt-bff
sudo chown svc-smartagt-bff /app/config/bff/tls/server.key
sudo chmod 600 /app/config/bff/tls/server.key
sudo install -d /etc/smartagt
sudo install -m 600 /dev/null /etc/smartagt/bff.env
sudoedit /etc/smartagt/bff.env
SMARTAGT_CORE_DATABASE_PASSWORD=<mot de passe du rôle smartagt_bff>
SMARTAGT_KEK=<KEK du Frontend>
SMARTAGT_INTERNAL_JOIN_SECRET=<secret de déploiement du coffre>
Créez l'unité du Frontend, /etc/systemd/system/smartagt-frontend-service.service :
[Unit]
Description=SmartAGT Frontend
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-bff
WorkingDirectory=/app/smartagt-bff-core
EnvironmentFile=/etc/smartagt/bff.env
ExecStart=/app/smartagt-bff-core/run.bin run --config /app/config/bff/smartagt-bff-core.yaml
StateDirectory=smartagt/bff
LogsDirectory=smartagt/bff
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
Une fois l'unité créée, lancez le service :
sudo systemctl daemon-reload
sudo systemctl enable --now smartagt-frontend-service
Le service se crée avec les commandes de Windows.
$password = [Net.NetworkCredential]::new('', (Read-Host 'Mot de passe du rôle smartagt_bff' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'KEK du Frontend' -AsSecureString)).Password
$joinSecret = [Net.NetworkCredential]::new('', (Read-Host 'Secret de déploiement' -AsSecureString)).Password
$name = 'smartagt-frontend-service'
New-Service -Name $name -DisplayName 'SmartAGT Frontend Service' -Description 'Interface web de SmartAGT.' -BinaryPathName '"C:\app\smartagt-bff-core\run.exe" run --config C:\app\config\bff\smartagt-bff-core.yaml' -StartupType Automatic | Out-Null
Set-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Services\$name" -Name Environment -Type MultiString -Value "SMARTAGT_CORE_DATABASE_PASSWORD=$password", "SMARTAGT_KEK=$kek", "SMARTAGT_INTERNAL_JOIN_SECRET=$joinSecret"
sc.exe failure $name reset= 86400 actions= restart/10000 | Out-Null
sc.exe failureflag $name 1 | Out-Null
Start-Service $name
Fermez ensuite la console.
Mode alternatif : NSSM héberge run.exe comme service. Installez nssm.exe 64 bits dans le PATH.
$password = [Net.NetworkCredential]::new('', (Read-Host 'Mot de passe du rôle smartagt_bff' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'KEK du Frontend' -AsSecureString)).Password
$joinSecret = [Net.NetworkCredential]::new('', (Read-Host 'Secret de déploiement' -AsSecureString)).Password
$name = 'smartagt-frontend-service'
nssm install $name C:\app\smartagt-bff-core\run.exe
nssm set $name DisplayName 'SmartAGT Frontend Service'
nssm set $name Description 'Interface web de SmartAGT.'
nssm set $name AppParameters 'run --config C:\app\config\bff\smartagt-bff-core.yaml'
nssm set $name AppDirectory C:\app\smartagt-bff-core
nssm set $name AppEnvironmentExtra "SMARTAGT_CORE_DATABASE_PASSWORD=$password" "SMARTAGT_KEK=$kek" "SMARTAGT_INTERNAL_JOIN_SECRET=$joinSecret"
nssm start $name
Fermez ensuite la console.
Résultat attendu : sur chaque nœud Frontend, la page de connexion s'affiche sur https://<nom du nœud>:9000, sans alerte de certificat.
Cas particuliers
Frontend sur un autre serveur que le Backend
Le guichet local du Backend n'écoute qu'en boucle locale : un Frontend installé sur un autre serveur se rattache par l'API Publique, avec un secret de déploiement. Avant l'étape 3 :
- Exposer le Backend. Sur le serveur du Backend, l'API Publique écoute sur l'adresse IP du serveur (
http.public.host, YAML Avancé d'Installer le Backend) ethttp.internal.urldésigne une adresse joignable depuis le serveur du Frontend (cas particulier « Frontend sur un autre serveur » de la même page). Ouvrez en entrée, sur le pare-feu du serveur du Backend, les ports8000et8010depuis le serveur du Frontend. - Générer le secret. Sur le serveur du Backend, dans une console où le mot de passe et la KEK du Backend sont saisis comme pour son
init, exécutezrun.bin pki generate-join-secret --configsuivi du YAML du Backend (run.exesous Windows). La commande écrit une ligne JSON : la valeurjoin_secretet son identifiant publicsecret_id. - Distribuer le secret. Enregistrez la valeur de
join_secretdans un fichier protégé, sur le serveur du Backend et sur celui du Frontend. AjoutezSMARTAGT_INTERNAL_JOIN_SECRET_FILE, avec le chemin de ce fichier, à l'environnement des services du Backend et du Frontend et à la session de l'étape 3. Le secret ne figure jamais dans un fichier YAML. Redémarrez l'API pour qu'elle lise le secret. - Pointer le Frontend. Dans le YAML du Frontend,
http.backend.base_urlreprend l'adresse et le port de l'API Publique du Backend, par exemplehttps://<adresse IP du serveur Backend>:8000.
init se rattache alors par l'API Publique, puis le trafic passe par le lien interne 8010. Un secret configuré ferme le guichet local de l'API qui le porte ; les Frontend ajoutés ensuite lisent l'identité commune dans leur base, sans nouveau rattachement.
Ajouter un nœud Frontend
Sur le nouveau nœud, appliquez les étapes 1 et 4 avec la KEK du Frontend et le secret de déploiement du coffre. Sautez les étapes 2 et 3 : le nœud lit l'identité commune dans la base. Ajoutez-le ensuite aux nœuds du reverse proxy.
Rappel
La connexion n'est admise que depuis les origines déclarées dans allow_origins et depuis celle de l'URL publique de la plateforme. Chaque origine reprend exactement l'adresse saisie par les postes : protocole, nom et port. Le bloc http se place sous smartagt, au même niveau que core : mal placé, il est ignoré sans erreur. Une origine absente laisse la page s'afficher mais refuse la connexion avec un 403. Après un changement de nom d'accès, complétez la liste puis redémarrez le Frontend : CORS.