Deployment
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
| Listener | Default | Exposure |
|---|---|---|
| HTTP data plane (HTTP/JSON, read-only GraphQL, MCP, A2A, search) | RELATA_PORT (9090), bind 127.0.0.1 | Set 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. |
| Admin | 127.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 serveThe 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
-
Install. Download a release for your platform and verify its signature and SBOM before installing, or build from source. The one-line
install.shand OS packages are not available yet; see Installation. -
Data directory. Set
RELATA_DATA_DIRto a persistent local volume. The directory takes an exclusive lock, so only onerelataprocess may use it at a time; a second process fails to start rather than splitting writes. -
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 -
TLS. Set
RELATA_TLS_CERTandRELATA_TLS_KEY, or terminate TLS at a proxy and setRELATA_PLAINTEXT_OK=truefor the non-loopback bind. -
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"}' -
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
| Item | Setting |
|---|---|
| Authentication | RELATA_ADMIN_TOKEN, bootstrap RELATA_BEARER_TOKEN, registry tokens minted per application |
| TLS | RELATA_TLS_CERT and RELATA_TLS_KEY, or proxy plus RELATA_PLAINTEXT_OK=true |
| Storage | RELATA_DATA_DIR on a persistent local volume |
| Backup | A separate destination and a tested restore into an empty directory; a job that completed is not a verified recovery point |
| Rate limiting | RELATA_RATE_LIMIT_RPS (default 10000) |
| Memory | Resident-memory budgets such as RELATA_STORE_MAX_RAM_MB, sized against your own data |
| Monitoring | RELATA_METRICS_PUBLIC=true for a scraper behind network-layer auth; RELATA_OTLP_ENDPOINT for traces |
| Logs | RELATA_LOG_FORMAT=json for log shippers |