Installation#

RelataDB ships as a single Rust binary — no JVM, no external services, no runtime dependencies. Docker is optional. The same binary serves all three deployment profiles (free, server, cluster); switching is one environment variable.

Prerequisites#

Note: Docker users skip Rust and protoc entirely — the image is self-contained.

Docker (recommended)#

The fastest path. The published image bundles the relata binary and defaults that work out of the box. The canonical image is ghcr.io/relatadb/relata (the same image is mirrored to Docker Hub as openworkbench/relata-db — pick whichever registry your environment prefers).

docker run -d -p 9090:9090 --name relata \
  ghcr.io/relatadb/relata:latest
 
# or, the Docker Hub mirror (same image):
docker run -d -p 9090:9090 --name relata \
  openworkbench/relata-db:latest

Verify:

curl http://127.0.0.1:9090/health
# {"status":"ok"}

To persist data to a host directory:

docker run -d -p 9090:9090 \
  -v "$PWD/relata-data:/data/relata" \
  --name relata \
  ghcr.io/relatadb/relata:latest

Production: pin to a specific tag (e.g. ghcr.io/relatadb/relata:2.0.0) and run relata check after startup. Using :latest in production is a reliability risk.

Pre-built Binary#

The signed install script downloads the correct pre-built binary for your platform and verifies its SHA-256 checksum:

curl -sSf https://relatadb.dev/install.sh | sh
relata --version

Supported targets: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin.

Build from Source#

Source access is available to licensees. Once you have access, build with Rust 1.85+, protoc, and cargo:

cargo install --path crates/relata-cli --locked    # → ~/.cargo/bin/relata
# or, without installing system-wide:
cargo build --workspace --release                  # → target/release/relata

--locked uses the exact dependency versions in Cargo.lock. Request source access via github.com/relatadb.

Note: unsafe is forbidden (#![forbid(unsafe_code)] in every crate) and missing_docs is denied.

Supply-chain check (optional but recommended before production):

cargo deny check

Verify the Install#

relata --version
# relata 2.0.0

Start the server and confirm it responds:

relata serve &
curl http://127.0.0.1:9090/health
# {"status":"ok"}

Run the full integration check suite (150+ checks covering storage, query, auth, and protocol compatibility):

relata check

Run relata check after every install or upgrade. It exercises the full server surface and catches misconfiguration before your workload does.

First-Run Checklist#

1. Start the server: relata serve
2. Confirm health: curl http://127.0.0.1:9090/health
3. Run a query: relata query "SELECT * FROM Person LIMIT 5"
4. Set a bearer token: RELATA_BEARER_TOKEN=your-secret relata serve
5. Choose a profile: RELATA_PROFILE=server relata serve
6. Run integration checks: relata check

Deployment Profiles#

Set RELATA_PROFILE to switch profiles. The binary is identical across all three.

free is the default so relata serve works immediately for evaluation. Move to server before handling real data.

lite was a legacy alias for free and is now rejected outright — startup fails if RELATA_PROFILE=lite is set. Use free.

Key CLI Commands#

All commands respect RELATA_PROFILE and the full RELATA_* environment variable matrix documented in Configuration.

Air-Gapped / Demo Mode#

There's no single air-gap switch — outbound calls are opt-in already. Leave RELATA_LLM_URL/RELATA_LLM_API_KEY and RELATA_OTLP_ENDPOINT unset and the node makes no LLM or telemetry calls.

To disable rate limits for load testing, benchmarks, or demo environments, raise the per-IP limiter values directly:

RELATA_RATE_LIMIT_RPS=99999 \
RELATA_RATE_LIMIT_AUTH_FAIL_RPS=99999 \
relata serve

Warning: Do not disable rate limits in production. They are part of the abuse-prevention posture. Use network-layer controls (mTLS sidecar, NetworkPolicy) if you need to enforce them at the infrastructure level instead.

Setting RELATA_RATE_LIMIT_AUTH_FAIL_RPS=0 is treated as 1 by the backend — zero is clamped to the minimum. Use 99999 to effectively disable the auth-fail bucket.

See Also#

• Quickstart — get running and issue your first query in five minutes
• Configuration — full environment variable reference
• Deployment — production topology, TLS, object storage