Aller au contenu

Installer le Frontend

Cette procédure installe le Frontend en quatre étapes.

  1. Package et YAMLDépôt et configuration
  2. KEKClé de chiffrement de clés
  3. InitialisationSchéma et rattachement
  4. ServiceFrontend

Prérequis

  • Backend installé et lancé : Installer le Backend.
  • Base smartagt_bff créé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_bff créé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
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

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 ;
  • 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
    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
    backend:
      base_url: https://<adresse IP du serveur>:8000        # API Publique du Backend : même adresse que son http.public.host

Pour cette configuration :

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_url sert au seul rattachement, le trafic passe ensuite par le lien interne 8010
  • 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
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
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 :

  1. 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) et http.internal.url dé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 ports 8000 et 8010 depuis le serveur du Frontend.
  2. 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écutez run.bin pki generate-join-secret --config suivi du YAML du Backend (run.exe sous Windows). La commande écrit une ligne JSON : la valeur join_secret et son identifiant public secret_id.
  3. Distribuer le secret. Enregistrez la valeur de join_secret dans un fichier protégé, sur le serveur du Backend et sur celui du Frontend. Ajoutez SMARTAGT_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.
  4. Pointer le Frontend. Dans le YAML du Frontend, http.backend.base_url reprend l'adresse et le port de l'API Publique du Backend, par exemple https://<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.