Skip to content

Configuration

YAML templates are supplied with the deliverables. Installation settings follow this precedence: YAML, then environment, then command arguments. init and persistent services must receive the same access settings, paths and secrets.

Files and paths

Purpose Linux Windows
Backend binaries /app/smartagt-backend-core/ C:\app\smartagt-backend-core\
Frontend service binaries /app/smartagt-bff-core/ C:\app\smartagt-bff-core\
Backend YAML /app/config/backend/smartagt-backend-core.yaml C:\app\config\backend\smartagt-backend-core.yaml
Frontend service YAML /app/config/bff/smartagt-bff-core.yaml C:\app\config\bff\smartagt-bff-core.yaml
Backend environment /etc/smartagt/backend.env C:\app\config\backend\environment.json
Frontend service environment /etc/smartagt/bff.env C:\app\config\bff\environment.json
S3 connection, if selected /app/s3.env C:\app\s3.json
Gateway environment /etc/smartagt/gateway.env C:\app\config\backend\gateway-environment.json
Component TLS /app/config/<component>/tls/ C:\app\config\<component>\tls\
Backend data /var/lib/smartagt/backend/ C:\app\data\backend\
Frontend service data /var/lib/smartagt/bff/ C:\app\data\bff\
Backend logs /var/log/smartagt/backend/ C:\app\logs\backend\
Frontend service logs /var/log/smartagt/bff/ C:\app\logs\bff\
PostgreSQL 18 Configuration /etc/postgresql/18/main/, data /var/lib/postgresql/18/main/ Binaries C:\app\PostgreSQL\18\bin\, data and configuration under data\

These are the procedure paths. Adapt them together. Root or Windows administrators manage binaries, while application accounts write only to their data and logs. Environment files contain secrets: mode 600 on Linux, restricted ACLs on Windows.

Initial settings

Environment names use _ between levels and __ for an underscore within a field: BASE__URL represents base_url.

YAML setting Environment variable Example
smartagt.core.database.host SMARTAGT_CORE_DATABASE_HOST localhost for a database on the same server
smartagt.core.database.port SMARTAGT_CORE_DATABASE_PORT 5432
smartagt.core.database.name SMARTAGT_CORE_DATABASE_NAME smartagt or smartagt_bff
smartagt.core.database.user SMARTAGT_CORE_DATABASE_USER Component role
smartagt.core.database.password SMARTAGT_CORE_DATABASE_PASSWORD Role secret
smartagt.http.public.host SMARTAGT_HTTP_PUBLIC_HOST Backend: 127.0.0.1 by default, server interface for clients on other hosts
smartagt.http.public.port SMARTAGT_HTTP_PUBLIC_PORT Backend: 8000
smartagt.http.public.tls_enabled SMARTAGT_HTTP_PUBLIC_TLS__ENABLED Backend: true. HTTPS is active by default, with a self-signed certificate; to install your own, see Install your certificates
smartagt.http.public.certfile SMARTAGT_HTTP_PUBLIC_CERTFILE Backend: server certificate path
smartagt.http.public.keyfile SMARTAGT_HTTP_PUBLIC_KEYFILE Backend: private key path
smartagt.http.reload SMARTAGT_HTTP_RELOAD Backend: false
smartagt.http.internal.url SMARTAGT_HTTP_INTERNAL_URL Backend: https://127.0.0.1:8010 by default; API node or load balancer name across multiple servers (plain layer 4 TCP passthrough, no TLS termination)
smartagt.http.server.host SMARTAGT_HTTP_SERVER_HOST Frontend service: listening interface, 0.0.0.0 for direct access
smartagt.http.server.port SMARTAGT_HTTP_SERVER_PORT Frontend service: 9000
smartagt.http.server.tls_enabled SMARTAGT_HTTP_SERVER_TLS__ENABLED Frontend service: true. HTTPS is active by default, with a self-signed certificate; to install your own, see Install your certificates
smartagt.http.server.certfile SMARTAGT_HTTP_SERVER_CERTFILE Frontend service: server certificate path
smartagt.http.server.keyfile SMARTAGT_HTTP_SERVER_KEYFILE Frontend service: private key path
smartagt.http.server.reload SMARTAGT_HTTP_SERVER_RELOAD Frontend service: false
smartagt.http.server.workers SMARTAGT_HTTP_SERVER_WORKERS Frontend service: 1 for the compiled binary
smartagt.http.backend.base_url SMARTAGT_HTTP_BACKEND_BASE__URL Frontend service: API Public listener used for enrollment, https://localhost:8000 on the same server, or the server IP address if the API listens on it
smartagt.http.cors.allow_origins[0] SMARTAGT_HTTP_CORS_ALLOW__ORIGINS_0 Frontend service: exact browser HTTPS origin
Dedicated variable Purpose
SMARTAGT_KEK Component KEK, generated once and kept in the vault
SMARTAGT_DATA_DIR, SMARTAGT_LOG_DIR Process data and log roots
PGSSLMODE=verify-full Encrypted PostgreSQL: full TLS validation of the server (PostgreSQL SSL)
PGSSLROOTCERT Encrypted PostgreSQL: PostgreSQL server CA
SMARTAGT_INTERNAL_JOIN_SECRET_FILE Path of the protected file holding the deployment secret, on the API side and the Frontend service side, when the first Frontend service runs without an API on its server
SMARTAGT_INTERNAL_JOIN_SECRET Same secret supplied directly; the file variant is recommended

The API, workers and Gateway share the Backend KEK. The Frontend service uses a separate KEK and PostgreSQL password. Losing a KEK prevents decryption of the data it protects. The deployment secret never appears in a YAML file.

Listeners and HTTP

The API process serves two listeners, Public and Internal; AI Gateway serves the third one, described below. Ports and clients of each listener appear in Network.

Block Fields Default values
smartagt.http.public host, port, tls_enabled, certfile, keyfile, trusted_proxies, timeout_keep_alive 127.0.0.1, 8000, HTTPS with a self-signed certificate, [], 5 s
smartagt.http.internal url, local_enrollment_port https://127.0.0.1:8010, 8011
smartagt.http max_request_size_mb, max_upload_size_mb, timeout_graceful_shutdown, reload 16 MB, 256 MB, 30 s; reload reserved for development
smartagt.http.backend (Frontend service) base_url, local_enrollment_port, timeout, limits Enrollment address, 8011, client timeouts and pool towards the API

The smartagt.http limits apply to both API listeners. The Internal listener requires no certificate or proxy setting. It closes an idle connection after 75 seconds and cleanly closes, after its response, a connection open for more than 5 minutes. The Frontend service reuses its connections: one TLS handshake per connection, not per request. Its pool expires idle connections before that delay; limits.keepalive_expiry is capped at 60 seconds. A certificate renewal or an authority rotation interrupts no exchange in progress.

smartagt.http.internal.url is an installation value: the first API to start records it, then only the run.bin pki internal-url set <url> command changes it. Then copy the new value into the YAML of every API node and restart it: a node whose value differs closes its Internal listener with the internal_url_mismatch cause. The Frontend service has nothing to change: when the recorded URL does not answer, it reads the current URL through smartagt.http.backend.base_url, at most every five minutes, with an exchange authenticated by its own secret. It adopts a URL only from the same installation and with the same session key; otherwise it reports backend_key_changed. smartagt.http.internal.local_enrollment_port and smartagt.http.backend.local_enrollment_port keep the same value.

Databases and processes

Database Owner Purpose
smartagt smartagt Platform and Gateway data, processing state
smartagt_vector smartagt Document indexes, vector extension
smartagt_bff smartagt_bff Frontend service sessions and data
Process Command Linux and Windows service Windows display name
API run SmartAGT-Platform-Service SmartAGT Platform Service
Ingestion worker --role=rag-ingestor smartagt-rag-ingestor-worker SmartAGT RAG Ingestor Worker
Embedding worker --role=rag-embed smartagt-rag-embed-worker SmartAGT RAG Embed Worker
Scheduling worker --role=scheduler smartagt-scheduler-worker SmartAGT Scheduler Worker
Frontend service run smartagt-frontend-service SmartAGT Frontend Service
Optional Gateway gateway SmartAGT-AI-Gateway-Service SmartAGT AI Gateway Service

Each command uses run.bin or run.exe, the correct --config and the component environment. On Linux, the Backend account is svc-smartagt-backend, and the Frontend service account is svc-smartagt-bff. Windows services created by the installation procedures use SYSTEM. Their commands are listed in Operations.

Topology

For a distributed installation, define the smartagt.deployment.nodes list before initialisation and the first Platform start. Supply this identical manifest in each Backend node’s YAML and preserve it for subsequent starts. Each entry describes component placement:

Field Value
node_id Stable, unique identifier of 1 to 40 letters, digits, hyphens or underscores, starting with a letter or digit
address DNS name or IP address reachable between nodes, without a port
components Roles present: platform, rag-ingestor, rag-embed, scheduler, gateway or bff for the Frontend service

Set SMARTAGT_NODE_ID in each Backend node’s local environment to its node_id. Load this identity with the other service variables. The Storage concept describes supported placements and the flow matrix lists connections to allow.

S3 connection

To use S3, set smartagt.mediastore.backend: s3 and provide endpoint_url and bucket under smartagt.mediastore.s3. region is optional depending on the provider. S3 is required in containers and available in native installations.

The access keys are secrets and never appear in the YAML: supply them through the environment, in SMARTAGT_MEDIASTORE_S3_ACCESS__KEY and SMARTAGT_MEDIASTORE_S3_SECRET__KEY. The double underscore is required: it stands for the one in the access_key and secret_key fields.

Configure S3 gives the values to place in the YAML and the variables to supply before init, then API and workers use the same connection settings. Storage explains persistence choices and placement.

Proxies and SSO

smartagt.http.public.trusted_proxies for the API Public listener and smartagt.http.server.trusted_proxies for the Frontend service contain only the IP addresses or CIDRs of proxies allowed to forward the client address. These lists alone decide which X-Forwarded-* headers are accepted. Without a proxy, keep [], never the entire user network.

On the Internal listener, the Backend takes the user address forwarded by the Frontend service, authenticated by its certificate: a single X-Forwarded-For header carrying a single valid address. The activity log and rate limiters therefore see the user's real address, without declaring the Frontend service as a trusted proxy.

For OIDC and Entra ID, Backend YAML must allow the browser origin:

smartagt:
  iam:
    oidc:
      frontend_allowed_origins:
        - "https://smartagt.example.org"

An empty list denies OIDC sign-ins. The origin must match the Frontend service, its CORS settings and the callback URLs registered with the identity provider. SSO configuration screens are documented inside the product.

AI Gateway

The smartagt.gateway.server block configures the Gateway listener, independent of the API listeners under smartagt.http:

Field Value or bound
host, port Planned interface, 8001
tls_enabled, certfile, keyfile Mandatory HTTPS: self-signed certificate by default, or pair installed through Install your certificates
trusted_proxies [] or exact Gateway proxy addresses
reload, workers false, 1
max_request_size_mb Default 16, from 1 to 64
max_concurrent_requests Default 64, from 1 to 512
body_timeout_seconds Default 30, from 1 to 120

Limits under smartagt.gateway.admission control request frequency and concurrency per key and principal. Multiple instances share admission through PostgreSQL; size their pools alongside Platform and worker pools. Activation, allowed client addresses and catalogs remain application settings.

Ports and flows · Install your certificates · Install the Backend · Install the Frontend.