Skip to content

Install the Backend

This procedure installs the Backend in four steps.

  1. Package and YAMLPlacement and configuration
  2. KEKKey encryption key
  3. InitializationSchema and admin account
  4. ServicesPlatform, workers and AI Gateway

Prerequisites

  • 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 8010 in front of the Platform nodes, for example api-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 8001 of 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 8000 and 8001 in 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.nodes declares 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 8000 and 8001 open to clients on other hosts, port 8010 to 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 admin account 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 admin account retrieved for the first sign-in
  • join_secret value 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
    sc.exe failureflag $service.Name 1 | 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
    sc.exe failureflag $service.Name 1 | 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.