Configuration#

RelataDB is configured through environment variables, with an optional relata.toml config file for persisted settings (search order: --config <path> flag, RELATA_CONFIG env var, ./relata.toml, then ~/.relata/config.toml). A bare relata serve starts in dev mode with safe defaults. Production requires three things: a profile, a bearer token, and (optionally) an object-store endpoint.

Strict parsing. Every RELATA_* value is validated at startup. A malformed value (e.g. RELATA_PORT=abc or RELATA_WAL_SYNC=true) causes a FATAL startup error — Relata refuses to boot rather than silently using a wrong default. Removed/renamed vars (e.g. RELATA_ORG_MODE) also FATAL.

Operator tools:

• relata config --print-template — emit a commented .env template of every RELATA_* var.
• relata config --validate — check your config before boot.
• relata config --migrate — auto-rewrite old var names to the current surface (run when upgrading from 1.x).
• relata doctor — 12 pre-flight checks (config, ports, KMS, disk).

Pick a profile first#

RELATA_PROFILE is the master switch. Set it before anything else.

# Local dev — no auth required, unbounded RAM, eager restart
RELATA_PROFILE=free relata serve
 
# Single-node production — 1 GB row-store RAM wall, disk-first walls on, requires bearer token
RELATA_PROFILE=server RELATA_BEARER_TOKEN=<your-strong-token> relata serve
 
# Multi-node (alpha) — same as server plus coordination
RELATA_PROFILE=cluster RELATA_BEARER_TOKEN=<your-strong-token> relata serve

lite was a legacy alias for free and is now rejected outright — startup fails if RELATA_PROFILE=lite is set; use free. The server and cluster profiles refuse to start without RELATA_BEARER_TOKEN set.

Domain profile#

RELATA_DOMAIN_PROFILE loads the matching ontology overlay and default detector packs.

RELATA_DOMAIN_PROFILE=finint relata serve

Environment variable reference#

Profile and deployment#

Auth#

Storage#

RAM and cache limits#

Cold-start and restart#

Search and embedding#

SmartIngest detector packs#

# Default
RELATA_DETECT_PACKS=network,contact,crypto
 
# Add financial and payment
RELATA_DETECT_PACKS=network,contact,crypto,financial,payment
 
# All packs
RELATA_DETECT_PACKS=all
 
# Disable detection
RELATA_DETECT_PACKS=none

Available opt-in additions: financial, payment, social, transport, device, ics.

Observability#

Rate limits#

To disable rate limits for load tests or air-gapped demos:

RELATA_RATE_LIMIT_RPS=99999 RELATA_RATE_LIMIT_AUTH_FAIL_RPS=99999 relata serve

Purpose enforcement#

Minimal production docker-compose#

Copy this, replace the token and bucket values, and run docker compose up -d.

services:
  relata:
    image: ghcr.io/relatadb/relata:latest
    restart: unless-stopped
    ports:
      - "9090:9090"
    environment:
      RELATA_PROFILE: server
      RELATA_BEARER_TOKEN: "change-me-use-openssl-rand-hex-32"
      RELATA_PORT: "9090"
      RELATA_DOMAIN_PROFILE: enterprise
      RELATA_PURPOSE_MODE: strict
      RELATA_PURPOSES: analytics,audit,compliance
      RELATA_STORE_MAX_RAM_MB: "2048"
      RELATA_LAZY_RESTART: "true"
      RELATA_HYDRATE_RECENT_SEGMENTS: "5"
      RELATA_LOG_FORMAT: json
      RELATA_LOG_LEVEL: info
      RELATA_OTLP_ENDPOINT: "http://otel-collector:4318/v1/traces"
      RELATA_METRICS_PUBLIC: "true"
      AWS_ENDPOINT_URL: "http://minio:9000"
      AWS_ACCESS_KEY_ID: minio
      AWS_SECRET_ACCESS_KEY: minio123
      RELATA_S3_BUCKET: relata-data
    volumes:
      - relata-data:/var/lib/relata
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9090/health"]
      interval: 10s
      timeout: 5s
      retries: 3
    depends_on:
      minio:
        condition: service_healthy
 
  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minio
      MINIO_ROOT_PASSWORD: minio123
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio-data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 10s
      timeout: 5s
      retries: 3
 
volumes:
  relata-data:
  minio-data:

Verify the node is healthy after startup:

curl http://localhost:9090/health
curl http://localhost:9090/health/ready
curl http://localhost:9090/version

Singleton enforcement#

relata serve acquires an exclusive flock on data_dir/relata.lock. If two pods share the same PVC, the second one fails with a clear error rather than silently splitting writes. This is especially important in Kubernetes rolling updates — use RollingUpdate strategy with maxUnavailable: 1 or switch to a StatefulSet.

See also#

• Auth & Security — bearer tokens, OIDC, mTLS, ACL
• Backup & Restore — WAL, Parquet, MinIO setup
• Scaling — RAM walls, paged backends, lazy restart
• Observability — logs, metrics, traces, health probes