Install the Backend
This procedure installs the Backend in four steps.
- Package and YAMLPlacement and configuration
- KEKKey encryption key
- InitializationSchema and admin account
- ServicesPlatform, workers and AI Gateway
Prerequisites
- Operating system meeting the prerequisites.
- Databases created: Prepare the databases.
- Backend package copied to the server.
- Operating system meeting the prerequisites on every node.
- Databases created, PostgreSQL reachable through its virtual address: Prepare the databases.
- S3 storage ready: Configure S3.
- TCP (L4) load balancer for the internal link
8010in front of the Platform nodes, for exampleapi-internal.example.test. - Backend package copied to every node.
Procedure
1. Place the package and create the configuration
sudo mkdir -p /app/config/backend
sudo tar -xzf <Backend package> -C /app
sudoedit /app/config/backend/smartagt-backend-core.yaml
New-Item -ItemType Directory -Force C:\app\config\backend | Out-Null
Expand-Archive <Backend package> C:\app\smartagt-backend-core
notepad C:\app\config\backend\smartagt-backend-core.yaml
Give smartagt-backend-core.yaml the content that matches your scenario:
smartagt:
core:
data_dir: /var/lib/smartagt/backend
log_dir: /var/log/smartagt/backend
database:
host: localhost
port: 5432
name: smartagt
user: smartagt
smartagt:
core:
data_dir: C:/app/data/backend
log_dir: C:/app/logs/backend
database:
host: localhost
port: 5432
name: smartagt
user: smartagt
With this base configuration, SmartAGT runs with:
- PostgreSQL on the same server, reached through
localhost, encrypted when the server offers it, without certificate verification - the Public API on the loopback interface (
127.0.0.1:8000), enough for a Frontend installed on this server - the Gateway, if you start it, on port
8001of every interface - self-signed certificates, generated by SmartAGT, for the Public API and the Gateway
smartagt:
core:
data_dir: /var/lib/smartagt/backend
log_dir: /var/log/smartagt/backend
database:
host: postgres.example.test # name carried by the server certificate
port: 5432
name: smartagt
user: smartagt
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:
public:
host: <server IP address> # Public API exposed to other hosts
certfile: /app/config/backend/tls/server.crt # Public API certificate
keyfile: /app/config/backend/tls/server.key # private key of this certificate
gateway:
server:
certfile: /app/config/backend/tls/gateway.crt # Gateway certificate
keyfile: /app/config/backend/tls/gateway.key # private key of this certificate
smartagt:
core:
data_dir: C:/app/data/backend
log_dir: C:/app/logs/backend
database:
host: postgres.example.test # name carried by the server certificate
port: 5432
name: smartagt
user: smartagt
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:
public:
host: <server IP address> # Public API exposed to other hosts
certfile: C:/app/config/backend/tls/server.crt # Public API certificate
keyfile: C:/app/config/backend/tls/server.key # private key of this certificate
gateway:
server:
certfile: C:/app/config/backend/tls/gateway.crt # Gateway certificate
keyfile: C:/app/config/backend/tls/gateway.key # private key of this certificate
For this configuration:
- place the Public API and Gateway certificates: Install your certificates
- place the PostgreSQL authority and prepare the server: PostgreSQL SSL
- open ports
8000and8001in the firewall for clients on other hosts
Expected result: the package is extracted and smartagt-backend-core.yaml is in place.
On every Backend node:
sudo mkdir -p /app/config/backend
sudo tar -xzf <Backend package> -C /app
sudoedit /app/config/backend/smartagt-backend-core.yaml
New-Item -ItemType Directory -Force C:\app\config\backend | Out-Null
Expand-Archive <Backend package> C:\app\smartagt-backend-core
notepad C:\app\config\backend\smartagt-backend-core.yaml
Give smartagt-backend-core.yaml the same content on every node. Only the Public API address changes:
smartagt:
core:
data_dir: /var/lib/smartagt/backend
log_dir: /var/log/smartagt/backend
database:
host: postgres.example.test # PostgreSQL virtual address
port: 5432
name: smartagt
user: smartagt
deployment:
nodes: # identical on every node
- node_id: platform-1
address: platform-1.example.test
components: [platform, scheduler, gateway]
- node_id: platform-2
address: platform-2.example.test
components: [platform, scheduler, gateway]
- node_id: worker-1
address: worker-1.example.test
components: [rag-ingestor, rag-embed]
mediastore:
backend: s3
s3:
endpoint_url: https://s3.example.test
bucket: smartagt-documents
region: eu-west-1
http:
public:
host: <IP address of this node> # Public API of this node
internal:
url: https://api-internal.example.test:8010 # internal link load balancer
smartagt:
core:
data_dir: C:/app/data/backend
log_dir: C:/app/logs/backend
database:
host: postgres.example.test # PostgreSQL virtual address
port: 5432
name: smartagt
user: smartagt
deployment:
nodes: # identical on every node
- node_id: platform-1
address: platform-1.example.test
components: [platform, scheduler, gateway]
- node_id: platform-2
address: platform-2.example.test
components: [platform, scheduler, gateway]
- node_id: worker-1
address: worker-1.example.test
components: [rag-ingestor, rag-embed]
mediastore:
backend: s3
s3:
endpoint_url: https://s3.example.test
bucket: smartagt-documents
region: eu-west-1
http:
public:
host: <IP address of this node> # Public API of this node
internal:
url: https://api-internal.example.test:8010 # internal link load balancer
With this configuration:
deployment.nodesdeclares every node and its roles:platform,rag-ingestor,rag-embed,scheduler,gateway- the S3 access keys come from the environment, in steps 3 and 4
- ports
8000and8001open to clients on other hosts, port8010to the internal link load balancer only
Expected result: on every node, the package is extracted and smartagt-backend-core.yaml is 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.
sudo /app/smartagt-backend-core/run.bin generate-kek
Once the KEK is saved in the vault, clear the screen with clear.
C:\app\smartagt-backend-core\run.exe generate-kek
Once the KEK is saved in the vault, clear the screen with Clear-Host.
Generate the KEK once, on a single node. Keep it in your vault: every Backend node reuses it.
sudo /app/smartagt-backend-core/run.bin generate-kek
Once the KEK is saved in the vault, clear the screen with clear.
C:\app\smartagt-backend-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 Backend: it creates the tables, sets up encryption and storage, then creates the admin account with a one-time password.
read -rsp 'Password of the smartagt role: ' SMARTAGT_CORE_DATABASE_PASSWORD; echo
read -rsp 'KEK: ' SMARTAGT_KEK; echo
export SMARTAGT_CORE_DATABASE_PASSWORD SMARTAGT_KEK
cd /app/smartagt-backend-core
sudo --preserve-env=SMARTAGT_CORE_DATABASE_PASSWORD,SMARTAGT_KEK ./run.bin init --config /app/config/backend/smartagt-backend-core.yaml
$env:SMARTAGT_CORE_DATABASE_PASSWORD = [Net.NetworkCredential]::new('', (Read-Host 'Password of the smartagt role' -AsSecureString)).Password
$env:SMARTAGT_KEK = [Net.NetworkCredential]::new('', (Read-Host 'KEK' -AsSecureString)).Password
Set-Location C:\app\smartagt-backend-core
.\run.exe init --config C:\app\config\backend\smartagt-backend-core.yaml
Expected result:
- initialization completes without error (exit code
0) - one-time password of the
adminaccount retrieved for the first sign-in
On the first Platform node only. This operation prepares the Backend: it creates the tables, sets up encryption and S3 storage, then creates the admin account with a one-time password. The last command produces the deployment secret that lets the Frontend nodes, which run on other servers, attach to the API.
read -rsp 'Password of the smartagt role: ' SMARTAGT_CORE_DATABASE_PASSWORD; echo
read -rsp 'KEK: ' SMARTAGT_KEK; echo
read -rsp 'S3 access key: ' SMARTAGT_MEDIASTORE_S3_ACCESS__KEY; echo
read -rsp 'S3 secret: ' SMARTAGT_MEDIASTORE_S3_SECRET__KEY; echo
export SMARTAGT_CORE_DATABASE_PASSWORD SMARTAGT_KEK SMARTAGT_MEDIASTORE_S3_ACCESS__KEY SMARTAGT_MEDIASTORE_S3_SECRET__KEY
export SMARTAGT_CLUSTER_ENABLED=true SMARTAGT_NODE_ID=platform-1
cd /app/smartagt-backend-core
sudo --preserve-env=SMARTAGT_CORE_DATABASE_PASSWORD,SMARTAGT_KEK,SMARTAGT_MEDIASTORE_S3_ACCESS__KEY,SMARTAGT_MEDIASTORE_S3_SECRET__KEY,SMARTAGT_CLUSTER_ENABLED,SMARTAGT_NODE_ID ./run.bin init --config /app/config/backend/smartagt-backend-core.yaml
sudo --preserve-env=SMARTAGT_CORE_DATABASE_PASSWORD,SMARTAGT_KEK,SMARTAGT_MEDIASTORE_S3_ACCESS__KEY,SMARTAGT_MEDIASTORE_S3_SECRET__KEY,SMARTAGT_CLUSTER_ENABLED,SMARTAGT_NODE_ID ./run.bin pki generate-join-secret --config /app/config/backend/smartagt-backend-core.yaml
$env:SMARTAGT_CORE_DATABASE_PASSWORD = [Net.NetworkCredential]::new('', (Read-Host 'Password of the smartagt role' -AsSecureString)).Password
$env:SMARTAGT_KEK = [Net.NetworkCredential]::new('', (Read-Host 'KEK' -AsSecureString)).Password
$env:SMARTAGT_MEDIASTORE_S3_ACCESS__KEY = [Net.NetworkCredential]::new('', (Read-Host 'S3 access key' -AsSecureString)).Password
$env:SMARTAGT_MEDIASTORE_S3_SECRET__KEY = [Net.NetworkCredential]::new('', (Read-Host 'S3 secret' -AsSecureString)).Password
$env:SMARTAGT_CLUSTER_ENABLED = 'true'
$env:SMARTAGT_NODE_ID = 'platform-1'
Set-Location C:\app\smartagt-backend-core
.\run.exe init --config C:\app\config\backend\smartagt-backend-core.yaml
.\run.exe pki generate-join-secret --config C:\app\config\backend\smartagt-backend-core.yaml
Expected result:
- initialization completes without error (exit code
0) - one-time password of the
adminaccount retrieved for the first sign-in join_secretvalue from the JSON line kept in the vault, next to the KEK
The other nodes do not run init: they join the installation when their services start.
4. Create and start the services
Platform, the three workers and AI Gateway run as services and start with the server.
Create the service account and the file holding its secrets:
sudo useradd --system --no-create-home --shell /usr/sbin/nologin svc-smartagt-backend
sudo install -d /etc/smartagt
sudo install -m 600 /dev/null /etc/smartagt/backend.env
sudoedit /etc/smartagt/backend.env
SMARTAGT_CORE_DATABASE_PASSWORD=<password of the smartagt role>
SMARTAGT_KEK=<KEK>
Create the five units, one per service:
/etc/systemd/system/SmartAGT-Platform-Service.service
[Unit]
Description=SmartAGT Platform
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-backend
WorkingDirectory=/app/smartagt-backend-core
EnvironmentFile=/etc/smartagt/backend.env
ExecStart=/app/smartagt-backend-core/run.bin run --config /app/config/backend/smartagt-backend-core.yaml
StateDirectory=smartagt/backend
LogsDirectory=smartagt/backend
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
/etc/systemd/system/smartagt-rag-ingestor-worker.service
[Unit]
Description=SmartAGT RAG-Ingestor Worker
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-backend
WorkingDirectory=/app/smartagt-backend-core
EnvironmentFile=/etc/smartagt/backend.env
ExecStartPre=/app/smartagt-backend-core/run.bin schema-wait --role rag-ingestor --timeout 300 --config /app/config/backend/smartagt-backend-core.yaml
ExecStart=/app/smartagt-backend-core/run.bin worker --role rag-ingestor --config /app/config/backend/smartagt-backend-core.yaml
StateDirectory=smartagt/backend
LogsDirectory=smartagt/backend
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
/etc/systemd/system/smartagt-rag-embed-worker.service
[Unit]
Description=SmartAGT RAG-Embed Worker
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-backend
WorkingDirectory=/app/smartagt-backend-core
EnvironmentFile=/etc/smartagt/backend.env
ExecStartPre=/app/smartagt-backend-core/run.bin schema-wait --role rag-embed --timeout 300 --config /app/config/backend/smartagt-backend-core.yaml
ExecStart=/app/smartagt-backend-core/run.bin worker --role rag-embed --config /app/config/backend/smartagt-backend-core.yaml
StateDirectory=smartagt/backend
LogsDirectory=smartagt/backend
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
/etc/systemd/system/smartagt-scheduler-worker.service
[Unit]
Description=SmartAGT Scheduler Worker
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-backend
WorkingDirectory=/app/smartagt-backend-core
EnvironmentFile=/etc/smartagt/backend.env
ExecStartPre=/app/smartagt-backend-core/run.bin schema-wait --role scheduler --timeout 300 --config /app/config/backend/smartagt-backend-core.yaml
ExecStart=/app/smartagt-backend-core/run.bin worker --role scheduler --config /app/config/backend/smartagt-backend-core.yaml
StateDirectory=smartagt/backend
LogsDirectory=smartagt/backend
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
/etc/systemd/system/SmartAGT-AI-Gateway-Service.service
[Unit]
Description=SmartAGT AI Gateway
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-backend
WorkingDirectory=/app/smartagt-backend-core
EnvironmentFile=/etc/smartagt/backend.env
ExecStart=/app/smartagt-backend-core/run.bin gateway --config /app/config/backend/smartagt-backend-core.yaml
StateDirectory=smartagt/backend
LogsDirectory=smartagt/backend
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
Once the five units exist, start the services:
sudo systemctl daemon-reload
sudo systemctl enable --now SmartAGT-Platform-Service smartagt-rag-ingestor-worker smartagt-rag-embed-worker smartagt-scheduler-worker SmartAGT-AI-Gateway-Service
The services are created with the Windows commands.
$password = [Net.NetworkCredential]::new('', (Read-Host 'Password of the smartagt role' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'KEK' -AsSecureString)).Password
$config = 'C:\app\config\backend\smartagt-backend-core.yaml'
$services = @(
@{ Name = 'SmartAGT-Platform-Service'; Display = 'SmartAGT Platform Service'; Arguments = "run --config $config"
Description = 'SmartAGT platform.' }
@{ Name = 'smartagt-rag-ingestor-worker'; Display = 'SmartAGT RAG-Ingestor Worker'; Arguments = "worker --role rag-ingestor --config $config"
Description = 'Extraction and chunking of the documents uploaded to SmartAGT.' }
@{ Name = 'smartagt-rag-embed-worker'; Display = 'SmartAGT RAG-Embed Worker'; Arguments = "worker --role rag-embed --config $config"
Description = 'Vector computation for SmartAGT documents.' }
@{ Name = 'smartagt-scheduler-worker'; Display = 'SmartAGT Scheduler Worker'; Arguments = "worker --role scheduler --config $config"
Description = 'SmartAGT scheduled tasks: maintenance, directory, email.' }
@{ Name = 'SmartAGT-AI-Gateway-Service'; Display = 'SmartAGT AI Gateway Service'; Arguments = "gateway --config $config"
Description = 'Access of connected tools to the SmartAGT models.' }
)
foreach ($service in $services) {
New-Service -Name $service.Name -DisplayName $service.Display -Description $service.Description -BinaryPathName "`"C:\app\smartagt-backend-core\run.exe`" $($service.Arguments)" -StartupType Automatic | Out-Null
Set-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Services\$($service.Name)" -Name Environment -Type MultiString -Value "SMARTAGT_CORE_DATABASE_PASSWORD=$password", "SMARTAGT_KEK=$kek"
sc.exe failure $service.Name reset= 86400 actions= restart/10000 | Out-Null
Start-Service $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 role' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'KEK' -AsSecureString)).Password
$config = 'C:\app\config\backend\smartagt-backend-core.yaml'
$services = @(
@{ Name = 'SmartAGT-Platform-Service'; Display = 'SmartAGT Platform Service'; Arguments = "run --config $config"
Description = 'SmartAGT platform.' }
@{ Name = 'smartagt-rag-ingestor-worker'; Display = 'SmartAGT RAG-Ingestor Worker'; Arguments = "worker --role rag-ingestor --config $config"
Description = 'Extraction and chunking of the documents uploaded to SmartAGT.' }
@{ Name = 'smartagt-rag-embed-worker'; Display = 'SmartAGT RAG-Embed Worker'; Arguments = "worker --role rag-embed --config $config"
Description = 'Vector computation for SmartAGT documents.' }
@{ Name = 'smartagt-scheduler-worker'; Display = 'SmartAGT Scheduler Worker'; Arguments = "worker --role scheduler --config $config"
Description = 'SmartAGT scheduled tasks: maintenance, directory, email.' }
@{ Name = 'SmartAGT-AI-Gateway-Service'; Display = 'SmartAGT AI Gateway Service'; Arguments = "gateway --config $config"
Description = 'Access of connected tools to the SmartAGT models.' }
)
foreach ($service in $services) {
nssm install $service.Name C:\app\smartagt-backend-core\run.exe
nssm set $service.Name DisplayName $service.Display
nssm set $service.Name Description $service.Description
nssm set $service.Name AppParameters $service.Arguments
nssm set $service.Name AppDirectory C:\app\smartagt-backend-core
nssm set $service.Name AppEnvironmentExtra "SMARTAGT_CORE_DATABASE_PASSWORD=$password" "SMARTAGT_KEK=$kek"
nssm start $service.Name
}
Then close the console.
Expected result: curl -k https://localhost:8000/api/v1/core/security/jwt/public-key (curl.exe on Windows) displays the public key of the API.
On every node, create the services of the roles that deployment.nodes assigns to it:
Role in components |
Service |
|---|---|
platform |
SmartAGT-Platform-Service |
rag-ingestor |
smartagt-rag-ingestor-worker |
rag-embed |
smartagt-rag-embed-worker |
scheduler |
smartagt-scheduler-worker |
gateway |
SmartAGT-AI-Gateway-Service |
Create the service account and the file holding its secrets:
sudo useradd --system --no-create-home --shell /usr/sbin/nologin svc-smartagt-backend
sudo install -d /etc/smartagt
sudo install -m 600 /dev/null /etc/smartagt/backend.env
sudoedit /etc/smartagt/backend.env
SMARTAGT_CORE_DATABASE_PASSWORD=<password of the smartagt role>
SMARTAGT_KEK=<KEK from the vault>
SMARTAGT_MEDIASTORE_S3_ACCESS__KEY=<S3 access key>
SMARTAGT_MEDIASTORE_S3_SECRET__KEY=<S3 secret>
SMARTAGT_CLUSTER_ENABLED=true
SMARTAGT_NODE_ID=<node_id of this node>
SMARTAGT_INTERNAL_JOIN_SECRET=<deployment secret from the vault>
Create the units of the roles carried by this node:
/etc/systemd/system/SmartAGT-Platform-Service.service
[Unit]
Description=SmartAGT Platform
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-backend
WorkingDirectory=/app/smartagt-backend-core
EnvironmentFile=/etc/smartagt/backend.env
ExecStart=/app/smartagt-backend-core/run.bin run --config /app/config/backend/smartagt-backend-core.yaml
StateDirectory=smartagt/backend
LogsDirectory=smartagt/backend
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
/etc/systemd/system/smartagt-rag-ingestor-worker.service
[Unit]
Description=SmartAGT RAG-Ingestor Worker
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-backend
WorkingDirectory=/app/smartagt-backend-core
EnvironmentFile=/etc/smartagt/backend.env
ExecStartPre=/app/smartagt-backend-core/run.bin schema-wait --role rag-ingestor --timeout 300 --config /app/config/backend/smartagt-backend-core.yaml
ExecStart=/app/smartagt-backend-core/run.bin worker --role rag-ingestor --config /app/config/backend/smartagt-backend-core.yaml
StateDirectory=smartagt/backend
LogsDirectory=smartagt/backend
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
/etc/systemd/system/smartagt-rag-embed-worker.service
[Unit]
Description=SmartAGT RAG-Embed Worker
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-backend
WorkingDirectory=/app/smartagt-backend-core
EnvironmentFile=/etc/smartagt/backend.env
ExecStartPre=/app/smartagt-backend-core/run.bin schema-wait --role rag-embed --timeout 300 --config /app/config/backend/smartagt-backend-core.yaml
ExecStart=/app/smartagt-backend-core/run.bin worker --role rag-embed --config /app/config/backend/smartagt-backend-core.yaml
StateDirectory=smartagt/backend
LogsDirectory=smartagt/backend
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
/etc/systemd/system/smartagt-scheduler-worker.service
[Unit]
Description=SmartAGT Scheduler Worker
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-backend
WorkingDirectory=/app/smartagt-backend-core
EnvironmentFile=/etc/smartagt/backend.env
ExecStartPre=/app/smartagt-backend-core/run.bin schema-wait --role scheduler --timeout 300 --config /app/config/backend/smartagt-backend-core.yaml
ExecStart=/app/smartagt-backend-core/run.bin worker --role scheduler --config /app/config/backend/smartagt-backend-core.yaml
StateDirectory=smartagt/backend
LogsDirectory=smartagt/backend
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
/etc/systemd/system/SmartAGT-AI-Gateway-Service.service
[Unit]
Description=SmartAGT AI Gateway
Wants=network-online.target
After=network-online.target
[Service]
User=svc-smartagt-backend
WorkingDirectory=/app/smartagt-backend-core
EnvironmentFile=/etc/smartagt/backend.env
ExecStart=/app/smartagt-backend-core/run.bin gateway --config /app/config/backend/smartagt-backend-core.yaml
StateDirectory=smartagt/backend
LogsDirectory=smartagt/backend
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
Once the units exist, start the services of this node:
sudo systemctl daemon-reload
sudo systemctl enable --now <services of this node>
The services are created with the Windows commands.
$password = [Net.NetworkCredential]::new('', (Read-Host 'Password of the smartagt role' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'KEK' -AsSecureString)).Password
$s3Key = [Net.NetworkCredential]::new('', (Read-Host 'S3 access key' -AsSecureString)).Password
$s3Secret = [Net.NetworkCredential]::new('', (Read-Host 'S3 secret' -AsSecureString)).Password
$joinSecret = [Net.NetworkCredential]::new('', (Read-Host 'Deployment secret' -AsSecureString)).Password
$nodeId = '<node_id of this node>'
$config = 'C:\app\config\backend\smartagt-backend-core.yaml'
# Keep in this list only the services of the roles carried by this node.
$services = @(
@{ Name = 'SmartAGT-Platform-Service'; Display = 'SmartAGT Platform Service'; Arguments = "run --config $config"
Description = 'SmartAGT platform.' }
@{ Name = 'smartagt-rag-ingestor-worker'; Display = 'SmartAGT RAG-Ingestor Worker'; Arguments = "worker --role rag-ingestor --config $config"
Description = 'Extraction and chunking of the documents uploaded to SmartAGT.' }
@{ Name = 'smartagt-rag-embed-worker'; Display = 'SmartAGT RAG-Embed Worker'; Arguments = "worker --role rag-embed --config $config"
Description = 'Vector computation for SmartAGT documents.' }
@{ Name = 'smartagt-scheduler-worker'; Display = 'SmartAGT Scheduler Worker'; Arguments = "worker --role scheduler --config $config"
Description = 'SmartAGT scheduled tasks: maintenance, directory, email.' }
@{ Name = 'SmartAGT-AI-Gateway-Service'; Display = 'SmartAGT AI Gateway Service'; Arguments = "gateway --config $config"
Description = 'Access of connected tools to the SmartAGT models.' }
)
foreach ($service in $services) {
New-Service -Name $service.Name -DisplayName $service.Display -Description $service.Description -BinaryPathName "`"C:\app\smartagt-backend-core\run.exe`" $($service.Arguments)" -StartupType Automatic | Out-Null
Set-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Services\$($service.Name)" -Name Environment -Type MultiString -Value "SMARTAGT_CORE_DATABASE_PASSWORD=$password", "SMARTAGT_KEK=$kek", "SMARTAGT_MEDIASTORE_S3_ACCESS__KEY=$s3Key", "SMARTAGT_MEDIASTORE_S3_SECRET__KEY=$s3Secret", 'SMARTAGT_CLUSTER_ENABLED=true', "SMARTAGT_NODE_ID=$nodeId", "SMARTAGT_INTERNAL_JOIN_SECRET=$joinSecret"
sc.exe failure $service.Name reset= 86400 actions= restart/10000 | Out-Null
Start-Service $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 role' -AsSecureString)).Password
$kek = [Net.NetworkCredential]::new('', (Read-Host 'KEK' -AsSecureString)).Password
$s3Key = [Net.NetworkCredential]::new('', (Read-Host 'S3 access key' -AsSecureString)).Password
$s3Secret = [Net.NetworkCredential]::new('', (Read-Host 'S3 secret' -AsSecureString)).Password
$joinSecret = [Net.NetworkCredential]::new('', (Read-Host 'Deployment secret' -AsSecureString)).Password
$nodeId = '<node_id of this node>'
$config = 'C:\app\config\backend\smartagt-backend-core.yaml'
# Keep in this list only the services of the roles carried by this node.
$services = @(
@{ Name = 'SmartAGT-Platform-Service'; Display = 'SmartAGT Platform Service'; Arguments = "run --config $config"
Description = 'SmartAGT platform.' }
@{ Name = 'smartagt-rag-ingestor-worker'; Display = 'SmartAGT RAG-Ingestor Worker'; Arguments = "worker --role rag-ingestor --config $config"
Description = 'Extraction and chunking of the documents uploaded to SmartAGT.' }
@{ Name = 'smartagt-rag-embed-worker'; Display = 'SmartAGT RAG-Embed Worker'; Arguments = "worker --role rag-embed --config $config"
Description = 'Vector computation for SmartAGT documents.' }
@{ Name = 'smartagt-scheduler-worker'; Display = 'SmartAGT Scheduler Worker'; Arguments = "worker --role scheduler --config $config"
Description = 'SmartAGT scheduled tasks: maintenance, directory, email.' }
@{ Name = 'SmartAGT-AI-Gateway-Service'; Display = 'SmartAGT AI Gateway Service'; Arguments = "gateway --config $config"
Description = 'Access of connected tools to the SmartAGT models.' }
)
foreach ($service in $services) {
nssm install $service.Name C:\app\smartagt-backend-core\run.exe
nssm set $service.Name DisplayName $service.Display
nssm set $service.Name Description $service.Description
nssm set $service.Name AppParameters $service.Arguments
nssm set $service.Name AppDirectory C:\app\smartagt-backend-core
nssm set $service.Name AppEnvironmentExtra "SMARTAGT_CORE_DATABASE_PASSWORD=$password" "SMARTAGT_KEK=$kek" "SMARTAGT_MEDIASTORE_S3_ACCESS__KEY=$s3Key" "SMARTAGT_MEDIASTORE_S3_SECRET__KEY=$s3Secret" 'SMARTAGT_CLUSTER_ENABLED=true' "SMARTAGT_NODE_ID=$nodeId" "SMARTAGT_INTERNAL_JOIN_SECRET=$joinSecret"
nssm start $service.Name
}
Then close the console.
Expected result: on every Platform node, curl -k https://<node IP address>:8000/api/v1/core/security/jwt/public-key (curl.exe on Windows) displays the public key of the API.
Special cases
Additional worker host
An additional worker host uses the same package, the same databases and the KEK of the existing Backend. Reuse the configuration and adapt the paths and addresses to this node. If S3 is chosen, every role uses the same bucket and the same connection settings.
Skip steps 2 and 3: the KEK comes from your vault and the database is already initialized. In step 4, create only the services of the workers planned on this node.
Distributed installation
Declare the topology in the shared YAML. Every node receives its identifier in SMARTAGT_NODE_ID, to add to the session before init and to the environment of its services.
Frontend on another server
Set http.internal.url to a name or address reachable from that server, identical in the YAML of every API node. It points to an API node or to a load balancer, which only passes TCP through (L4) on this link and does not terminate TLS. The first API to start records this URL. To change it later, run run.bin pki internal-url set <url>, copy the new value into the YAML of every API node, then restart each of them: a node whose value differs closes its internal listener. The Frontend service finds the new URL by itself through its attachment address, within five minutes, as long as the public listener remains reachable.
The deployment secret and the rest of the attachment are described in Install the Frontend.
S3 storage
Apply Configure S3, then copy the six indicated settings into the YAML before initialization. API and workers read the same connection.
Change the internal URL
The first API to start records http.internal.url. To change it later, run run.bin pki internal-url set <url>, copy the new value into the YAML of every Platform node, then restart each of them. A node whose value differs closes its internal listener. The Frontend finds the new URL by itself within five minutes.
Add a Backend node
Declare the new node in deployment.nodes, in the YAML of every node: running nodes read it at their next restart. On the new node, apply step 1 with this shared YAML. Skip steps 2 and 3: the KEK and the deployment secret come from the vault, the database is already initialized. In step 4, create the services of its roles.