Configuration Reference¶
Audience: Administrators configuring a Sentari server deployment
This page lists every setting an operator would normally change, its default, whether it is required, and how to set it for each deployment method. It complements the step-by-step guides (Docker Compose, Kubernetes, OpenShift), which show how to apply configuration; this page is the catalogue of what you can set.
Advanced internal tuning knobs (signing-key IDs, envelope size caps, install-gate proxy endpoints) are intentionally omitted — they default sensibly and are rarely changed. See Advanced settings at the end for where they live.
How configuration is applied¶
Sentari reads all application settings from environment variables prefixed
with SENTARI_. There are three ways to provide them:
| Method | How | When |
|---|---|---|
| Docker Compose | Set the variable in .env (copied from .env.example in your bundle) |
Single-VM / evaluation |
| Helm (K8s / OpenShift) | Set the corresponding values.yaml key, or add raw env to extraEnv |
Production clusters |
| Secret files | Set SENTARI_<NAME>_FILE=/path/to/file instead of the plain variable; Sentari reads the value from that file at startup |
Docker/K8s mounted secrets |
_FILE secret pattern — supported for the most sensitive values so they
never land in process environment:
SECRET_KEY, CONFIG_KEY, JWT_SECRET_KEY, CA_PASSPHRASE_KEY,
TOTP_DERIVATION_KEY, LICENSE_KEY, ENROLLMENT_TOKEN,
PROXY_ENROLLMENT_TOKEN, BOOTSTRAP_ADMIN_PASSWORD, FLOWER_BASIC_AUTH,
DATABASE_URL, REDIS_URL. The plain variable takes precedence if both are set.
Helm extraEnv — settings without a dedicated values.yaml key (OIDC,
LDAP, the KEK split, proxy_auth) are applied through the extraEnv list,
which is injected into the API, worker, and beat pods:
extraEnv:
- name: SENTARI_OIDC_ISSUER_URL
value: "https://login.example.com/realms/sentari"
- name: SENTARI_OIDC_CLIENT_SECRET
valueFrom:
secretKeyRef: { name: my-oidc-secret, key: client-secret }
Unknown variables are ignored silently. A typo such as
SENTARI_SECRT_KEYdoes not error — the server falls back to the default. Double-check names against this page.
Container image¶
| Variable | Helm value | Default | Notes |
|---|---|---|---|
REGISTRY (compose) |
image.registry + image.repository |
ghcr.io/sentari-dev/sentari |
Point at your mirror for air-gap. See Private Registry. |
VERSION (compose) |
image.tag |
latest (compose) / chart appVersion (Helm) |
Pin a specific release in production. |
Core infrastructure¶
| Variable | Helm value | Default | Required | Notes |
|---|---|---|---|---|
SENTARI_DATABASE_URL |
secrets.databaseUrl (external) |
postgresql+psycopg2://sentari:sentari@localhost:5432/sentari |
✅ | Compose builds it from POSTGRES_PASSWORD. Helm bundled DB builds it from secrets.dbPassword. |
POSTGRES_PASSWORD (compose) |
secrets.dbPassword |
— | ✅ | Database password (bundled DB). |
SENTARI_REDIS_URL |
secrets.redisUrl (external) |
redis://localhost:6379/0 |
✅ | Compose/Helm build it from the Redis password. |
REDIS_PASSWORD (compose) |
secrets.redisPassword |
— | ✅ | Redis AUTH password. |
For external managed databases, set database.external=true / redis.external=true
in Helm and provide the full URLs. See Plain PostgreSQL.
Security & secrets¶
| Variable | Helm value | Default | Required | Notes |
|---|---|---|---|---|
SENTARI_SECRET_KEY |
secrets.secretKey |
CHANGE-ME-IN-PRODUCTION |
✅ | JWT/HMAC anchor. Server refuses to start with the default. Generate: python3 -c "import secrets; print(secrets.token_hex(32))" |
SENTARI_CONFIG_KEY |
secrets.configKey |
(empty) | ⚠️ | AES-256-GCM key (base64, 32 bytes) encrypting admin-UI secrets (SIEM/SMTP/NVD/license). Required once you configure any of those — writes return 5xx without it. Generate: python3 -c "import os,base64; print(base64.b64encode(os.urandom(32)).decode())" |
SENTARI_MTLS_REQUIRED |
config.mtlsRequired |
true |
— | Require agent client certs on /scan + /config. Setting false requires SENTARI_DEBUG=true or the server refuses to boot. |
SENTARI_PROXY_AUTH_SECRET |
extraEnv |
(empty) | — | Shared secret the TLS terminator injects as X-Sentari-Proxy-Auth; adds app-layer proof a request came through your terminator. |
SENTARI_DEBUG |
extraEnv |
false |
— | Never true in production. Conscious opt-out that allows posture-weakening settings (mTLS off, license phone-home off) to run. |
KEK split (optional, recommended for production)¶
By default SENTARI_SECRET_KEY is reused for JWT signing, the CA passphrase,
TOTP-at-rest encryption, and OIDC CSRF-state. Set any of these to isolate one
duty; each falls back to SENTARI_SECRET_KEY when unset. The server logs a
WARNING for each that collapses onto SECRET_KEY.
| Variable | Helm value | Default | Notes |
|---|---|---|---|
SENTARI_JWT_SECRET_KEY |
extraEnv |
falls back to SECRET_KEY |
JWT HS256 signing key. Rotatable with zero downtime. |
SENTARI_CA_PASSPHRASE_KEY |
extraEnv |
falls back to SECRET_KEY |
Encrypts the internal CA private key at rest. |
SENTARI_TOTP_DERIVATION_KEY |
extraEnv |
falls back to SECRET_KEY |
HKDF input for TOTP secret encryption. |
SENTARI_OIDC_STATE_KEY |
extraEnv |
falls back to SECRET_KEY |
OIDC CSRF-state / nonce / PKCE binding. |
Agent enrollment & bootstrap admin¶
| Variable | Helm value | Default | Required | Notes |
|---|---|---|---|---|
SENTARI_ENROLLMENT_TOKEN |
secrets.enrollmentToken |
(empty) | ✅ (prod) | Token agents present on first registration. Empty = no check (dev only). Rotate after rollout. |
SENTARI_PROXY_ENROLLMENT_TOKEN |
extraEnv |
(empty) | — | Separate token for Sentari-Proxy enrolment (client_type=proxy). |
SENTARI_BOOTSTRAP_ADMIN_EMAIL |
secrets.bootstrapAdminEmail |
(empty) | ✅ | First admin account, created on first startup only. |
SENTARI_BOOTSTRAP_ADMIN_PASSWORD |
secrets.bootstrapAdminPassword |
(empty) | ✅ | First admin password. Change it after first login. |
Licensing¶
| Variable | Helm value | Default | Required | Notes |
|---|---|---|---|---|
SENTARI_LICENSE_KEY |
secrets.licenseKey |
(empty) | ✅ | License issued by license.sentari.dev. Without it the server boots but blocks writes (HTTP 402). |
SENTARI_LICENSE_SERVER_URL |
license.serverUrl |
https://license.sentari.dev |
— | License validation endpoint. Override for a private relay. |
| (air-gap) | license.mode: airgap |
online |
— | Air-gap mode: server makes no outbound license calls and uses the pre-signed SENTARI_LICENSE_KEY. Chart refuses to render if airgap is set while serverUrl still points at the vendor SaaS. |
SENTARI_LICENSE_PHONE_HOME_DISABLED |
extraEnv |
false |
— | Local-dev only. Skips license revalidation; requires SENTARI_DEBUG=true or the server FATALs. Air-gap deployments do not use this — they use license.mode: airgap. |
Authentication — OIDC / SSO¶
Supports Keycloak, Azure Entra ID, Ping, Okta, etc. All applied via Helm extraEnv.
| Variable | Default | Notes |
|---|---|---|
SENTARI_OIDC_ISSUER_URL |
(empty) | e.g. https://login.microsoftonline.com/{tenant}/v2.0. Empty disables OIDC. |
SENTARI_OIDC_CLIENT_ID |
(empty) | OAuth client ID. |
SENTARI_OIDC_CLIENT_SECRET |
(empty) | OAuth client secret (use a secretKeyRef). |
SENTARI_OIDC_SCOPES |
openid email profile |
Space-separated scopes. |
SENTARI_OIDC_AUTO_CREATE_USERS |
true |
Auto-provision users on first SSO login. |
SENTARI_OIDC_DEFAULT_ROLE |
viewer |
Role for auto-provisioned users. |
SENTARI_OIDC_ROLE_CLAIM |
(empty) | IdP claim holding the role (e.g. roles, groups). |
Authentication — LDAP / Active Directory¶
All applied via Helm extraEnv.
| Variable | Default | Notes |
|---|---|---|
SENTARI_LDAP_URL |
(empty) | ldaps://dc.example.com:636. Empty disables LDAP. ldap:// is refused unless ALLOW_PLAINTEXT. |
SENTARI_LDAP_BASE_DN |
(empty) | Search base, e.g. dc=example,dc=com. |
SENTARI_LDAP_BIND_DN |
(empty) | Service-account DN. |
SENTARI_LDAP_BIND_PASSWORD |
(empty) | Service-account password (use a secretKeyRef). |
SENTARI_LDAP_ALLOW_PLAINTEXT |
false |
Permit unencrypted ldap://. Air-gapped test only — production must use ldaps://. |
SENTARI_LDAP_CA_CERTS_FILE |
(unset) | PEM bundle for a private CA fronting ldaps://. |
Networking & CORS¶
| Variable | Helm value | Default | Notes |
|---|---|---|---|
SENTARI_ALLOWED_ORIGINS |
config.allowedOrigins |
["http://localhost:5173","http://localhost:8001"] |
JSON array of CORS origins. Set to your dashboard hostname in production. |
SENTARI_FORWARDED_ALLOW_IPS |
(start.sh / extraEnv) | 127.0.0.1 |
uvicorn --forwarded-allow-ips. Set to your TLS terminator's IP/CIDR when running behind a reverse proxy, so client IPs in audit/rate-limit are trusted. |
Outbound proxy (optional)¶
Used by Sentari for CVE feeds, license validation, and SIEM webhooks.
| Variable | Helm value | Default | Notes |
|---|---|---|---|
SENTARI_HTTP_PROXY |
proxy.httpProxy |
(empty) | Forward proxy for outbound HTTP. |
SENTARI_HTTPS_PROXY |
proxy.httpsProxy |
(empty) | Forward proxy for outbound HTTPS. |
SENTARI_NO_PROXY |
proxy.noProxy |
localhost,127.0.0.1 |
Bypass list. Helm auto-appends in-cluster service names. |
Observability¶
These are read directly from the environment (not SENTARI_-prefixed settings).
| Variable | Default | Notes |
|---|---|---|
SENTARI_LOG_LEVEL |
INFO |
DEBUG / INFO / WARNING / ERROR. |
SENTARI_LOG_FORMAT |
(console) | Set to json for structured logs (SIEM ingestion). |
SENTARI_METRICS_PORT |
9100 |
Prometheus /metrics port on the Celery worker. |
Flower (Celery monitoring — opt-in)¶
| Variable | Helm value | Default | Notes |
|---|---|---|---|
SENTARI_FLOWER_BASIC_AUTH |
secrets.flowerBasicAuth |
— | user:password. Required when Flower is enabled — the service refuses to start without it. |
SENTARI_FLOWER_BIND (compose) |
(N/A — kubectl port-forward) |
127.0.0.1 |
Bind address for the Flower port. |
Advanced settings¶
The following default sensibly and are rarely changed. Authoritative defaults and inline documentation are provided in the release bundle's configuration files (the environment template, the Helm values file, and the server configuration documentation included with your release).
- CA paths & hardening —
SENTARI_CA_CERT_PATH,SENTARI_CA_KEY_PATH,SENTARI_CA_REQUIRE_ENCRYPTED_KEY(fail closed on an unencrypted CA key). - JWT token lifetimes —
SENTARI_JWT_ACCESS_TOKEN_EXPIRE_MINUTES(15),SENTARI_JWT_REFRESH_TOKEN_EXPIRE_HOURS(8),SENTARI_JWT_ALGORITHM(HS256). - Signed-envelope channels — license-map / vuln-map / install-gate signing key paths, key IDs, and envelope record caps.
- Install-gate —
SENTARI_INSTALL_GATE_ENABLED, per-ecosystem proxy endpoints, rule caps. - License tamper-evidence —
SENTARI_LICENSE_PUBLIC_KEY_PATH,SENTARI_LICENSE_TAMPER_PHONE_HOME. - Agent self-update —
SENTARI_AGENT_RELEASE_DIR.