Configuration
RELATA_PROFILE accepts only free), no clustering and no licensing variables, and the variables of the retired protocol doors have no effect. The complete variable list is the environment variable reference.Relata DB is configured through environment variables, with an optional relata.toml for persisted settings. Precedence is env > file > built-in default. The file is searched in this order: --config <path>, RELATA_CONFIG, ./relata.toml, ~/.relata/relata.toml.
Strict parsing. Every
RELATA_*value is validated at startup. A malformed value (for exampleRELATA_PORT=abcorRELATA_WAL_SYNC=true) is a FATAL startup error: Relata refuses to boot rather than use a wrong default. Retired and renamed variables fail too.Operator tools
relata config --print-templateemits a commented.envtemplate of every variable.relata config --validatechecks your configuration before boot.relata doctorruns pre-flight checks (configuration, ports, disk).
The minimum for a network-facing node
A bare relata serve refuses to start without an authentication decision. A node is network-facing when its HTTP bind is not loopback; that needs tokens and TLS.
| Variable | Why |
|---|---|
RELATA_DATA_DIR | WAL, data and the token registry. Use a persistent local volume. |
RELATA_HTTP_BIND | Defaults to loopback. Set an address only to expose the data plane. |
RELATA_PORT | Data-plane port, default 9090. |
RELATA_BEARER_TOKEN | Loopback-only bootstrap secret. It does not authenticate the data plane. |
RELATA_ADMIN_TOKEN | Secret for the loopback admin listener (RELATA_ADMIN_BIND, default 127.0.0.1:9091). Supply it on every restart. |
RELATA_TLS_CERT, RELATA_TLS_KEY | In-process TLS, or use a proxy plus RELATA_PLAINTEXT_OK=true. |
Keep secrets in a secret manager, make the two tokens distinct, and never set RELATA_OPEN_DEV_ALLOWED or RELATA_AUTH_MODE=none in production. See Auth and security and Deployment.
Common settings
| Area | Variables | Notes |
|---|---|---|
| Storage | RELATA_DATA_DIR, RELATA_LOCAL_DATA_DIR, AWS_ENDPOINT_URL with RELATA_S3_BUCKET | Local disk by default; an S3-compatible endpoint selects object-store persistence. The object store is the primary data backend, not an independent backup. |
| Durability | RELATA_WAL_SYNC | always, interval (default) or off. Any other value is fatal. |
| Memory | RELATA_STORE_MAX_RAM_MB and the other resident-memory budgets | Size against your own data; see Capacity and WAL retention. |
| Restart | RELATA_LAZY_RESTART, RELATA_HYDRATE_RECENT_SEGMENTS | Lazy restart loads the manifest catalog only and hydrates segments on demand. |
| Search | RELATA_SEARCH_PRESET, RELATA_EMBED_URL | Embedding is optional; queries fall back to lexical search when it is unset. |
| Detection | RELATA_DETECT_PACKS | SmartIngest detector packs, for example network,contact,crypto; none disables detection. |
| Purpose | RELATA_PURPOSE_MODE, RELATA_PURPOSES | strict accepts only registered purposes. |
| Observability | RELATA_LOG_FORMAT, RELATA_LOG_LEVEL, RELATA_OTLP_ENDPOINT, RELATA_METRICS_PUBLIC | OpenTelemetry is off while RELATA_OTLP_ENDPOINT is unset. |
| Rate limits | RELATA_RATE_LIMIT_RPS, RELATA_RATE_LIMIT_AUTH_FAIL_RPS | Raise them for load tests only; do not disable them in production. |
Domain overlays use RELATA_DOMAIN_PROFILE (enterprise, lea, finint, security, custom) and select the ontology overlay and default detector packs. That is an ontology choice, unrelated to deployment profiles.
Single-node compose example
Copy this, replace the secrets and run docker compose up -d. The data directory is a named volume; there is one service because there is one node.
services:
relata:
image: ghcr.io/relatadb/relata:latest # pin a version tag in production
restart: unless-stopped
ports:
- "9090:9090"
environment:
RELATA_BEARER_TOKEN: "change-me-use-openssl-rand-hex-32"
RELATA_ADMIN_TOKEN: "change-me-too-a-different-value"
RELATA_HTTP_BIND: "0.0.0.0:9090"
RELATA_PLAINTEXT_OK: "true" # TLS is terminated at your proxy
RELATA_DATA_DIR: /var/lib/relata
RELATA_PURPOSE_MODE: strict
RELATA_PURPOSES: analytics,audit,compliance
RELATA_LAZY_RESTART: "true"
RELATA_LOG_FORMAT: json
volumes:
- relata-data:/var/lib/relata
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9090/health"]
interval: 10s
timeout: 5s
retries: 3
volumes:
relata-data:Port 9090 must be reachable only through your TLS proxy or network policy. Do not publish the admin port. After startup:
curl http://localhost:9090/health
curl http://localhost:9090/health/ready
curl http://localhost:9090/versionSingleton enforcement
relata serve takes an exclusive lock on <data_dir>/relata.lock. A second process, or a second pod on the same volume, fails to start rather than splitting writes. During a Kubernetes rollout use the Recreate strategy, or a one-replica StatefulSet.