Configuration

Relata DB 3.0
This page describes Relata DB 3.0, the current release. There are no deployment profiles (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 example RELATA_PORT=abc or RELATA_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-template emits a commented .env template of every variable.
  • relata config --validate checks your configuration before boot.
  • relata doctor runs 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.

VariableWhy
RELATA_DATA_DIRWAL, data and the token registry. Use a persistent local volume.
RELATA_HTTP_BINDDefaults to loopback. Set an address only to expose the data plane.
RELATA_PORTData-plane port, default 9090.
RELATA_BEARER_TOKENLoopback-only bootstrap secret. It does not authenticate the data plane.
RELATA_ADMIN_TOKENSecret for the loopback admin listener (RELATA_ADMIN_BIND, default 127.0.0.1:9091). Supply it on every restart.
RELATA_TLS_CERT, RELATA_TLS_KEYIn-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

AreaVariablesNotes
StorageRELATA_DATA_DIR, RELATA_LOCAL_DATA_DIR, AWS_ENDPOINT_URL with RELATA_S3_BUCKETLocal disk by default; an S3-compatible endpoint selects object-store persistence. The object store is the primary data backend, not an independent backup.
DurabilityRELATA_WAL_SYNCalways, interval (default) or off. Any other value is fatal.
MemoryRELATA_STORE_MAX_RAM_MB and the other resident-memory budgetsSize against your own data; see Capacity and WAL retention.
RestartRELATA_LAZY_RESTART, RELATA_HYDRATE_RECENT_SEGMENTSLazy restart loads the manifest catalog only and hydrates segments on demand.
SearchRELATA_SEARCH_PRESET, RELATA_EMBED_URLEmbedding is optional; queries fall back to lexical search when it is unset.
DetectionRELATA_DETECT_PACKSSmartIngest detector packs, for example network,contact,crypto; none disables detection.
PurposeRELATA_PURPOSE_MODE, RELATA_PURPOSESstrict accepts only registered purposes.
ObservabilityRELATA_LOG_FORMAT, RELATA_LOG_LEVEL, RELATA_OTLP_ENDPOINT, RELATA_METRICS_PUBLICOpenTelemetry is off while RELATA_OTLP_ENDPOINT is unset.
Rate limitsRELATA_RATE_LIMIT_RPS, RELATA_RATE_LIMIT_AUTH_FAIL_RPSRaise 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/version

Singleton 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.

See also