Deployment

Relata DB 3.0
This page describes Relata DB 3.0: one binary, one machine, one tenant. The 2.5.8 profile, cluster and Kubernetes pages are kept in the frozen version snapshots. What was and was not measured is recorded in 3.0 evidence status; nothing here is a performance, availability or durability guarantee.

Relata DB 3.0 is the open edition: it runs on a single machine, has no clustering or replication, and serves one tenant (default). Clustering, high availability, several tenants and managed users belong to Relata Enterprise DB; see Editions and limits and the What is new in 3.0.

There are no deployment profiles to choose between. RELATA_PROFILE accepts only free (the default); server and cluster stop startup. The security posture follows configuration: the bind address, TLS and tokens.

Listeners

ListenerDefaultExposure
HTTP data plane (HTTP/JSON, read-only GraphQL, MCP, A2A, search)RELATA_PORT (9090), bind 127.0.0.1Set RELATA_HTTP_BIND to expose it. Exposure requires TLS: in-process with RELATA_TLS_CERT and RELATA_TLS_KEY, or terminated at a proxy with RELATA_PLAINTEXT_OK=true.
Admin127.0.0.1:9091 (RELATA_ADMIN_BIND, must be loopback)Never publish. Reach it from the host, a port-forward or a sidecar sharing the network namespace.

The PostgreSQL, MongoDB, Redis, Neo4j, ClickHouse, S3, Bolt and Arrow Flight listeners are retired; see Retired protocol doors and Migrating from retired doors.

Local development

A token-less relata serve refuses to start. For a loopback-only loop, opt in explicitly:

RELATA_AUTH_MODE=none RELATA_OPEN_DEV_ALLOWED=true relata serve

The open-dev convenience works only on a loopback bind and never through a published container port. Anything reachable off the machine needs real tokens.

Production on one machine

  1. Install. Download a release for your platform and verify its signature and SBOM before installing, or build from source. The one-line install.sh and OS packages are not available yet; see Installation.

  2. Data directory. Set RELATA_DATA_DIR to a persistent local volume. The directory takes an exclusive lock, so only one relata process may use it at a time; a second process fails to start rather than splitting writes.

  3. Secrets. Provide two distinct high-entropy values from your secret manager:

    export RELATA_BEARER_TOKEN=$(openssl rand -hex 32)   # bootstrap secret, not a data-plane credential
    export RELATA_ADMIN_TOKEN=$(openssl rand -hex 32)    # admin listener, supplied on every restart
  4. TLS. Set RELATA_TLS_CERT and RELATA_TLS_KEY, or terminate TLS at a proxy and set RELATA_PLAINTEXT_OK=true for the non-loopback bind.

  5. Start and mint a token. The data plane accepts registry-minted tokens, not RELATA_BEARER_TOKEN. Mint one on the loopback admin listener:

    relata serve &
    curl -s -X POST http://127.0.0.1:9091/admin/tokens \
      -H "Authorization: Bearer $RELATA_ADMIN_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"description":"my-app"}'
  6. Verify.

    relata doctor                              # pre-flight checks
    curl http://127.0.0.1:9090/health/ready    # ready for traffic

Run the service under a supervisor (systemd or equivalent) with restart on failure and a raised file-descriptor limit. In a container, copy the compose file from Installation: the image needs explicit RELATA_* environment to start, and the data directory must be a persistent volume. With Kubernetes, run a single replica with a Recreate strategy (or a one-replica StatefulSet) on a single read-write volume; two pods on the same volume would contend for the data-directory lock.

Startup and shutdown

Startup acquires the data-directory lock, loads persisted state, replays the WAL, rebuilds the identity index and then binds the listeners. Start-up time grows with the amount of data; see Capacity planning and WAL retention for what has and has not been measured.

relata stop (or SIGTERM) stops accepting connections, drains in-flight queries (up to RELATA_DRAIN_TIMEOUT_SECS), flushes the WAL according to the configured durability policy, writes the final manifest and releases the lock. A crash, a host loss and a storage failure have different durability boundaries; do not assume one recovery guarantee. See Backup and restore.

Production checklist

ItemSetting
AuthenticationRELATA_ADMIN_TOKEN, bootstrap RELATA_BEARER_TOKEN, registry tokens minted per application
TLSRELATA_TLS_CERT and RELATA_TLS_KEY, or proxy plus RELATA_PLAINTEXT_OK=true
StorageRELATA_DATA_DIR on a persistent local volume
BackupA separate destination and a tested restore into an empty directory; a job that completed is not a verified recovery point
Rate limitingRELATA_RATE_LIMIT_RPS (default 10000)
MemoryResident-memory budgets such as RELATA_STORE_MAX_RAM_MB, sized against your own data
MonitoringRELATA_METRICS_PUBLIC=true for a scraper behind network-layer auth; RELATA_OTLP_ENDPOINT for traces
LogsRELATA_LOG_FORMAT=json for log shippers

See also