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.