Skip to content
NamiDB NamiDB

Docker + MinIO

The repo root ships a docker-compose.yml that brings up:

  • MinIO — S3-compatible bucket with the admin console on :9001.
  • bucket-init — one-shot container that creates the namidb bucket.
  • namidb-server — the daemon, authenticated with a bearer token, exposing the REST API on :8080.

Everything talks to MinIO over the docker network; nothing escapes the host.

Prerequisites

  • Docker (docker --version) and Compose v2 (docker compose version).
  • A local clone of the repo for the compose file and Dockerfile:
Terminal window
git clone https://github.com/namidb/namidb
cd namidb

1. Build the server image

Terminal window
docker build -t namidb-server:0.1 -f crates/namidb-server/Dockerfile .

The 0.1 tag is the one docker-compose.yml references. Cargo.lock is tracked in the repository as of 0.4.1, so this builds reproducibly from a fresh clone.

2. Mint an auth token

Terminal window
export NAMIDB_AUTH_TOKEN=$(openssl rand -hex 32)

docker-compose.yml refuses to start if NAMIDB_AUTH_TOKEN is unset — that’s the ${NAMIDB_AUTH_TOKEN:?…} substitution in the file.

3. Boot the stack

Terminal window
docker compose up -d

Compose brings up MinIO, waits for it to be healthy, runs the bucket-init container to create the namidb bucket, then starts the namidb-server daemon. After a few seconds you can hit it:

Terminal window
curl -s http://localhost:8080/v0/health | jq .

4. Run your first query

Terminal window
curl -s -X POST http://localhost:8080/v0/cypher \
  -H "Authorization: Bearer $NAMIDB_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query": "CREATE (a:Person {name: \"Alice\", age: 30}) RETURN a.name AS name"}' \
  | jq .


curl -s -X POST http://localhost:8080/v0/cypher \
  -H "Authorization: Bearer $NAMIDB_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query": "MATCH (p:Person) RETURN p.name AS name, p.age AS age"}' \
  | jq .

The MinIO console is on http://localhost:9001 (login: minioadmin / minioadmin). The namidb bucket will fill up with manifests, WAL segments, and SSTs as you write.

What’s inside the file

The compose file (and the server inside it) reads its config from the environment:

VariableValue used in compose
NAMIDB_STOREs3://namidb?ns=prod&endpoint=http://minio:9000&region=us-east-1&allow_http=true
NAMIDB_LISTEN0.0.0.0:8080
NAMIDB_AUTH_TOKEN${NAMIDB_AUTH_TOKEN:?set NAMIDB_AUTH_TOKEN in your env (e.g. openssl rand -hex 32)} (required at boot)
NAMIDB_FLUSH_INTERVAL30s
AWS_ACCESS_KEY_IDminioadmin
AWS_SECRET_ACCESS_KEYminioadmin
RUST_LOGinfo

The MinIO service mounts a named volume (minio-data) so the bucket survives docker compose down. Use docker compose down -v to wipe the data.

Swap MinIO for any S3-compatible bucket

The namidb-server container only knows about MinIO through its environment. To point the same stack at AWS S3, Cloudflare R2, or LocalStack, only NAMIDB_STORE and the credentials change:

# AWS S3
NAMIDB_STORE: "s3://my-bucket/data?ns=prod&region=us-east-1"
AWS_ACCESS_KEY_ID: "AKIA..."
AWS_SECRET_ACCESS_KEY: "..."


# Cloudflare R2
NAMIDB_STORE: "s3://my-bucket?ns=prod&endpoint=https://<acct>.r2.cloudflarestorage.com&region=auto"
AWS_ACCESS_KEY_ID: "<R2 token id>"
AWS_SECRET_ACCESS_KEY: "<R2 token secret>"

Or drop the MinIO + bucket-init services and run the daemon container alone. Everything else (auth, flags, endpoints) stays identical.

What’s next

  • HTTP server — the full flag and endpoint reference for the binary running inside the container.
  • MinIO — using MinIO outside of Docker.
  • Configuration — every env var the server reads.