Skip to content

Install the Frontend

This procedure installs the Frontend in four steps.

  1. Package and YAMLPlacement and configuration
  2. KEKKey encryption key
  3. InitializationSchema and attachment
  4. ServiceFrontend

Prerequisites

  • Backend installed and running: Install the Backend.
  • smartagt_bff database created: Prepare the databases.
  • Frontend package copied to the server.
  • DNS name used by the workstations, for example smartagt.example.test, resolving to this server.
  • Backend installed and running on its nodes, deployment secret in the vault: Install the Backend.
  • smartagt_bff database created: Prepare the databases.
  • Frontend package copied to every Frontend node.
  • For every Frontend node, a certificate and its key, issued for the name under which the reverse proxy verifies the nodes: SmartAGT generates this certificate only on a single server.

Procedure

1. Place the package and create the configuration

sudo mkdir -p /app/config/bff
sudo tar -xzf <Frontend package> -C /app
sudoedit /app/config/bff/smartagt-bff-core.yaml
New-Item -ItemType Directory -Force C:\app\config\bff | Out-Null
Expand-Archive <Frontend package> C:\app\smartagt-bff-core
notepad C:\app\config\bff\smartagt-bff-core.yaml

Give smartagt-bff-core.yaml the content that matches your scenario:

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"    # address typed by the workstations
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"    # address typed by the workstations

With this base configuration, the Frontend runs with:

  • PostgreSQL on the same server, reached through localhost
  • the web interface on port 9000, to open for inbound traffic in the server firewall
  • sign-in allowed from the origin declared in allow_origins, copied exactly from the workstations' address bar, scheme, name and port included: CORS
  • a certificate generated by SmartAGT for this port
  • the Public API reached at https://localhost:8000
smartagt:
  core:
    data_dir: /var/lib/smartagt/bff
    log_dir: /var/log/smartagt/bff
    database:
      host: postgres.example.test                           # name carried by the server certificate
      port: 5432
      name: smartagt_bff
      user: smartagt_bff
      sslmode: verify-full                                  # encryption required, server name verified
      sslrootcert: /app/cert/postgresql-ca.crt              # PostgreSQL certificate authority, optional if it is in the system store
  http:
    server:
      certfile: /app/config/bff/tls/server.crt              # certificate presented on port 9000
      keyfile: /app/config/bff/tls/server.key               # private key of this certificate
      trusted_proxies: []                                   # addresses of your reverse proxy
    cors:
      allow_origins:
        - "https://smartagt.example.test:9000"              # address typed by the workstations
    backend:
      base_url: https://<server IP address>:8000            # Backend Public API: same address as its http.public.host
smartagt:
  core:
    data_dir: C:/app/data/bff
    log_dir: C:/app/logs/bff
    database:
      host: postgres.example.test                           # name carried by the server certificate
      port: 5432
      name: smartagt_bff
      user: smartagt_bff
      sslmode: verify-full                                  # encryption required, server name verified
      sslrootcert: C:/app/cert/postgresql-ca.crt            # PostgreSQL certificate authority, optional if it is in the system store
  http:
    server:
      certfile: C:/app/config/bff/tls/server.crt            # certificate presented on port 9000
      keyfile: C:/app/config/bff/tls/server.key             # private key of this certificate
      trusted_proxies: []                                   # addresses of your reverse proxy
    cors:
      allow_origins:
        - "https://smartagt.example.test:9000"              # address typed by the workstations
    backend:
      base_url: https://<server IP address>:8000            # Backend Public API: same address as its http.public.host

For this configuration:

  • place the certificate and its key: Install your certificates
  • place the PostgreSQL authority and prepare the server: PostgreSQL SSL
  • declare in allow_origins the address typed by the workstations, the reverse proxy's when there is one: CORS
  • with a reverse proxy, declare its addresses in trusted_proxies
  • for a Frontend on another server than the Backend, follow the special cases

Expected result: the package is extracted and smartagt-bff-core.yaml is in place.

On every Frontend node:

sudo mkdir -p /app/config/bff/tls
sudo tar -xzf <Frontend package> -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 <Frontend package> 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

Give smartagt-bff-core.yaml the same content on every Frontend node:

smartagt:
  core:
    data_dir: /var/lib/smartagt/bff
    log_dir: /var/log/smartagt/bff
    database:
      host: postgres.example.test                       # PostgreSQL virtual address
      port: 5432
      name: smartagt_bff
      user: smartagt_bff
  http:
    server:
      certfile: /app/config/bff/tls/server.crt          # certificate of this node
      keyfile: /app/config/bff/tls/server.key           # private key of this certificate
    backend:
      base_url: https://platform-1.example.test:8000    # Public API of a Platform node, for the attachment
smartagt:
  core:
    data_dir: C:/app/data/bff
    log_dir: C:/app/logs/bff
    database:
      host: postgres.example.test                       # PostgreSQL virtual address
      port: 5432
      name: smartagt_bff
      user: smartagt_bff
  http:
    server:
      certfile: C:/app/config/bff/tls/server.crt        # certificate of this node
      keyfile: C:/app/config/bff/tls/server.key         # private key of this certificate
    backend:
      base_url: https://platform-1.example.test:8000    # Public API of a Platform node, for the attachment

With this configuration:

  • every node presents its own certificate on port 9000
  • base_url only serves the attachment, traffic then goes through the internal link 8010
  • the reverse proxy is declared after the installation: Configure a reverse proxy

Expected result: on every Frontend node, the package is extracted, and the certificate and smartagt-bff-core.yaml are in place.

2. Generate the key encryption key (KEK)

Keep the KEK in your vault: without it, the secrets stored in the database cannot be read.

Generate the Frontend KEK once, on a single Frontend node. Keep it in your vault: every Frontend node reuses it, and without it the secrets stored in the database cannot be read.

sudo /app/smartagt-bff-core/run.bin generate-kek

Once the KEK is saved in the vault, clear the screen with clear.

C:\app\smartagt-bff-core\run.exe generate-kek

Once the KEK is saved in the vault, clear the screen with Clear-Host.

3. Initialize

This operation prepares the Frontend: it creates the tables, sets up encryption, then attaches the Frontend to the Backend API.

read -rsp 'Password of the smartagt_bff role: ' 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 'Password of the smartagt_bff role' -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

Expected result:

  • initialization completes without error (exit code 0)
  • Frontend attached to the API, without warning

On the first Frontend node only. This operation prepares the Frontend: it creates the tables, sets up encryption, then attaches the Frontend to the API with the deployment secret.

read -rsp 'Password of the smartagt_bff role: ' SMARTAGT_CORE_DATABASE_PASSWORD; echo
read -rsp 'KEK: ' SMARTAGT_KEK; echo
read -rsp 'Deployment secret: ' 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 'Password of the smartagt_bff role' -AsSecureString)).Password
$env:SMARTAGT_KEK = [Net.NetworkCredential]::new('', (Read-Host 'KEK' -AsSecureString)).Password
$env:SMARTAGT_INTERNAL_JOIN_SECRET = [Net.NetworkCredential]::new('', (Read-Host 'Deployment secret' -AsSecureString)).Password
Set-Location C:\app\smartagt-bff-core
.\run.exe init --config C:\app\config\bff\smartagt-bff-core.yaml

Expected result:

  • initialization completes without error (exit code 0)
  • Frontend attached to the API, without warning

The other Frontend nodes do not run init: they read the shared identity from the database when their service starts.

4. Create and start the service

The Frontend runs as a service and starts with the server. It receives the password and the KEK through its own environment.

Create the service account and the file holding its 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=<password of the smartagt_bff role>
SMARTAGT_KEK=<Frontend KEK>

Create the Frontend unit, /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

Once the unit exists, start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now smartagt-frontend-service

The service is created with the Windows commands.

$password = [Net.NetworkCredential]::new('', (Read-Host 'Password of the smartagt_bff role' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'Frontend KEK' -AsSecureString)).Password
$name = 'smartagt-frontend-service'
New-Service -Name $name -DisplayName 'SmartAGT Frontend Service' -Description 'SmartAGT web interface.' -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

Then close the console.

Alternative mode: NSSM hosts run.exe as a service. Install the 64-bit nssm.exe in the PATH.

$password = [Net.NetworkCredential]::new('', (Read-Host 'Password of the smartagt_bff role' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'Frontend KEK' -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 'SmartAGT web interface.'
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

Then close the console.

Expected result: the sign-in page opens at https://smartagt.example.test:9000.

Note

The browser flags the certificate generated by SmartAGT: accept the warning for this address only, or install your own certificate with Install your certificates.

On every Frontend node, the service receives the password, the KEK and the deployment secret through its own environment.

Create the service account, give it the certificate key, then create the file holding its 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=<password of the smartagt_bff role>
SMARTAGT_KEK=<Frontend KEK>
SMARTAGT_INTERNAL_JOIN_SECRET=<deployment secret from the vault>

Create the Frontend unit, /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

Once the unit exists, start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now smartagt-frontend-service

The service is created with the Windows commands.

$password = [Net.NetworkCredential]::new('', (Read-Host 'Password of the smartagt_bff role' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'Frontend KEK' -AsSecureString)).Password
$joinSecret = [Net.NetworkCredential]::new('', (Read-Host 'Deployment secret' -AsSecureString)).Password
$name = 'smartagt-frontend-service'
New-Service -Name $name -DisplayName 'SmartAGT Frontend Service' -Description 'SmartAGT web interface.' -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

Then close the console.

Alternative mode: NSSM hosts run.exe as a service. Install the 64-bit nssm.exe in the PATH.

$password = [Net.NetworkCredential]::new('', (Read-Host 'Password of the smartagt_bff role' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'Frontend KEK' -AsSecureString)).Password
$joinSecret = [Net.NetworkCredential]::new('', (Read-Host 'Deployment secret' -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 'SmartAGT web interface.'
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

Then close the console.

Expected result: on every Frontend node, the sign-in page opens at https://<node name>:9000, without certificate warning.

Special cases

Frontend on another server than the Backend

The Backend local enrollment desk only listens on the loopback interface: a Frontend installed on another server attaches through the Public API, with a deployment secret. Before step 3:

  1. Expose the Backend. On the Backend server, the Public API listens on the server IP address (http.public.host, Advanced YAML of Install the Backend) and http.internal.url points to an address reachable from the Frontend server (special case "Frontend on another server" on the same page). In the Backend server firewall, open ports 8000 and 8010 for inbound traffic from the Frontend server.
  2. Generate the secret. On the Backend server, in a console where the Backend password and KEK are entered as for its init, run run.bin pki generate-join-secret --config followed by the Backend YAML (run.exe on Windows). The command writes a JSON line: the join_secret value and its public identifier secret_id.
  3. Distribute the secret. Save the join_secret value in a protected file on the Backend server and on the Frontend server. Add SMARTAGT_INTERNAL_JOIN_SECRET_FILE, with the path of this file, to the environment of the Backend and Frontend services and to the step 3 session. The secret never appears in a YAML file. Restart the API so that it reads the secret.
  4. Point the Frontend. In the Frontend YAML, http.backend.base_url uses the address and port of the Backend Public API, for example https://<Backend server IP address>:8000.

init then attaches through the Public API, and traffic goes through the internal link 8010. A configured secret closes the local enrollment desk of the API that carries it. Frontend instances added later read the shared identity from their database, without a new attachment.

Add a Frontend node

On the new node, apply steps 1 and 4 with the Frontend KEK and the deployment secret from the vault. Skip steps 2 and 3: the node reads the shared identity from the database. Then add it to the reverse proxy nodes.

Reminder

Sign-in is only allowed from the origins declared in allow_origins and from the origin of the platform public URL. Each origin matches exactly the address typed by the workstations: scheme, name and port. The http block sits under smartagt, at the same level as core: misplaced, it is ignored without error. A missing origin lets the page load but refuses sign-in with a 403. After a change of access name, complete the list, then restart the Frontend: CORS.