Single-node Strata#

A single-node deployment runs one strata process. It is the simplest shape Strata ships and the recommended starting point for labs, evaluation, and single-tenant pilots. The gateway is HTTP-stateless — durability lives in the metadata + data backends — so a single replica is not an HA shape: the box is the SPOF for HTTP traffic. For HA, see Multi-replica cluster.

Prerequisites#

• One Linux host (or a macOS workstation for dev).
• Docker (for the full stack) or Go 1.23+ (for the in-memory smoke).
• 2 vCPU + 1 GiB RSS baseline (see Sizing below).

The pure-memory path needs no other software. The Cassandra-backed path needs cassandra:5.0 reachable on :9042. The full stack (Cassandra + RADOS) is bootstrapped from the bundled compose file.

Install#

Three combinations are supported. Pick one.

Pure memory — zero-dep dev:

make run-memory          # boots strata on :8080, no Docker, no persistence

Cassandra metadata + memory data — persistent metadata, ephemeral object bytes:

make up && make wait-cassandra
make run-cassandra       # boots strata on :8080 against cassandra:5.0

Full stack — Cassandra + RADOS:

make up-all && make wait-cassandra && make wait-ceph
# gateway exposed on host :9999

For the TiKV-backed variant, see Docker Compose.

Configure#

The supported metadata × data combinations:

Top env vars (full table at Reference — environment variables):

The memory backend is for tests and the smoke pass; never use it for anything you care about. RADOS requires the ceph build tag (go build -tags ceph ./...); the bundled Dockerfile builds that variant.

Verify#

curl http://127.0.0.1:8080/healthz   # 200 once HTTP listener is bound
curl http://127.0.0.1:8080/readyz    # 200 once metadata + data probes pass
aws --endpoint-url http://127.0.0.1:8080 --no-sign-request s3 mb s3://test
aws --endpoint-url http://127.0.0.1:8080 --no-sign-request s3 cp README.md s3://test/

make run-memory runs auth-off (STRATA_AUTH_MODE=""), so aws-cli must pass --no-sign-request. To exercise SigV4 locally, set STRATA_AUTH_MODE=required + STRATA_STATIC_CREDENTIALS=admin:adminpass:owner before launching — see Get Started for the full credential table.

The operator console (when the gateway runs on :8080) lives at http://127.0.0.1:8080/console/ — note the trailing slash.

Monitor#

The gateway exposes two endpoints regardless of STRATA_AUTH_MODE:

• GET /healthz — liveness. Always 200 once the HTTP listener is bound. Use as the Kubernetes livenessProbe.
• GET /readyz — readiness. Fans out probes to the metadata backend and the data backend with a 1 s timeout. Returns 200 only when every probe passes. Use as the readiness probe + the LB health-check target.

Both bypass auth and the access-log middleware.

Prometheus scrape: :9000/metrics on the gateway (or whichever port STRATA_LISTEN advertises). OTel tracing enables when OTEL_EXPORTER_OTLP_ENDPOINT is set; the in-process trace ring buffer (STRATA_OTEL_RINGBUF=on, default) lets the operator console browse spans without an external collector. Dashboards + alert recipes live under Operate and Best Practices.

Sizing#

The gateway itself is cheap. The metadata + data backends are where most of the budget goes. Per-replica baseline (single-tenant, mixed read/write ≤200 RPS, mean object 256 KiB):

Troubleshoot#

• /readyz returns 503. A metadata or data probe is failing. Inspect gateway logs (JSON stdout) for probe failed lines; check Cassandra / TiKV connectivity and RADOS pool status.
• aws-cli SignatureDoesNotMatch. Either the LB / proxy is rewriting the Host header (SigV4 signs it) or STRATA_STATIC_CREDENTIALS and the client credentials disagree. Run with --debug to see the canonical request shape.
• make run-memory fails to bind :8080. Another process owns the port. Set STRATA_LISTEN=:8081 and retry.
• macOS + lima Docker: make up needs DOCKER_HOST=unix:///Users/.../.lima/.../sock/docker.sock so the Docker socket is reachable.
• First-bucket PUT works, GET returns 503. RADOS pool not ready. Wait for make wait-ceph; check ceph -s inside the container.

Production checklist#

When promoting a single-node deployment past lab:

• STRATA_AUTH_MODE=required set; root credentials stored outside the env file.
• STRATA_CONFIG_FILE mounted read-only with the runtime TOML.
• STRATA_LOG_LEVEL=INFO (or WARN for noisy clusters); JSON log handler is the default.
• Prometheus scraping /metrics; alerts on strata_worker_panic_total > 0.
• OTel collector pointed at via OTEL_EXPORTER_OTLP_ENDPOINT; sample ratio tuned via STRATA_OTEL_SAMPLE_RATIO.
• External log shipper draining stdout (JSON) into the central store.
• /healthz + /readyz wired into systemd / supervisord / Kubernetes probes.
• Backups configured for the metadata backend (Cassandra snapshots, TiKV PITR) and the data backend (RADOS pool snapshots or upstream-S3 versioning) — see Operate — backup & restore.
• Smoke pass scheduled (make smoke or make smoke-signed) post-deploy.

Cross-references#

• Get Started — 5-minute first run.
• Docker Compose — bundled compose file and supported profiles.
• Multi-replica cluster — when one box is no longer enough.
• Operate — day-2 workflows.
• Reference — environment variables — full env knob table.
• Architecture — Storage — backend selection, object-table sharding, RADOS chunking.