Install the Frontend
This procedure installs the Frontend in four steps.
- Package and YAMLPlacement and configuration
- KEKKey encryption key
- InitializationSchema and attachment
- ServiceFrontend
Prerequisites
- Backend installed and running: Install the Backend.
smartagt_bffdatabase 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_bffdatabase 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_originsthe 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_urlonly serves the attachment, traffic then goes through the internal link8010- 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:
- 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) andhttp.internal.urlpoints to an address reachable from the Frontend server (special case "Frontend on another server" on the same page). In the Backend server firewall, open ports8000and8010for inbound traffic from the Frontend server. - Generate the secret. On the Backend server, in a console where the Backend password and KEK are entered as for its
init, runrun.bin pki generate-join-secret --configfollowed by the Backend YAML (run.exeon Windows). The command writes a JSON line: thejoin_secretvalue and its public identifiersecret_id. - Distribute the secret. Save the
join_secretvalue in a protected file on the Backend server and on the Frontend server. AddSMARTAGT_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. - Point the Frontend. In the Frontend YAML,
http.backend.base_urluses the address and port of the Backend Public API, for examplehttps://<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.