Skip to content

Docker + MinIO

This recipe runs namidb-server against a MinIO bucket with Docker Compose. It mirrors the docker-compose.yml in the engine repository and uses the official image, so nothing is built locally.

Any S3-compatible server that enforces conditional writes (If-None-Match: *) works the same way: change the image and the endpoint= in the store URI. See Object stores.

The Compose file

services:
minio:
image: minio/minio
command: server /data --console-address ":9001"
environment:
MINIO_ROOT_USER: minioadmin
MINIO_ROOT_PASSWORD: minioadmin
volumes:
- minio-data:/data
ports:
- "127.0.0.1:9000:9000"
- "127.0.0.1:9001:9001"
healthcheck:
test: ["CMD", "mc", "ready", "local"]
interval: 3s
retries: 30
bucket-init:
image: minio/mc
depends_on:
minio:
condition: service_healthy
entrypoint: >
sh -c "
mc alias set local http://minio:9000 minioadmin minioadmin &&
mc mb --ignore-existing local/namidb
"
namidb-server:
image: namidb/namidb-server:3.3.0
depends_on:
bucket-init:
condition: service_completed_successfully
environment:
NAMIDB_STORE: "s3://namidb?ns=prod&endpoint=http://minio:9000&region=us-east-1&allow_http=true"
NAMIDB_AUTH_TOKEN: "${NAMIDB_AUTH_TOKEN:?set NAMIDB_AUTH_TOKEN (openssl rand -hex 32)}"
NAMIDB_BOLT_LISTEN: "0.0.0.0:7687"
# Admit work up to 90% of the container memory limit below.
NAMIDB_MEMORY_MAX_BYTES: "auto"
# Bounded RAM tier plus a persistent, reconstructible NVMe range cache.
NAMIDB_RAM_PAGE_CACHE_MAX_BYTES: "67108864"
NAMIDB_NVME_CACHE_PATH: "/var/cache/namidb-ranges"
NAMIDB_NVME_CACHE_MAX_BYTES: "10737418240"
NAMIDB_RANGE_CACHE_NAMESPACE: "compose-minio-prod"
AWS_ACCESS_KEY_ID: "minioadmin"
AWS_SECRET_ACCESS_KEY: "minioadmin"
RUST_LOG: "info"
ports:
- "127.0.0.1:8080:8080"
- "127.0.0.1:7687:7687"
mem_limit: 4g
volumes:
- namidb-spool:/var/tmp/namidb-spool
- namidb-range-cache:/var/cache/namidb-ranges
volumes:
minio-data: {}
namidb-spool: {}
namidb-range-cache: {}

What each part is for:

  • minio / bucket-init start the object store and create the namidb bucket. The ports are bound to 127.0.0.1; publish them more widely only behind your own access controls, and change the default MinIO credentials.
  • NAMIDB_STORE points the server at the bucket. endpoint= is the in-network MinIO address, allow_http=true allows plain HTTP to it, and region= is required by the S3 client (any value works for MinIO).
  • mem_limit + NAMIDB_MEMORY_MAX_BYTES=auto give the process a hard cgroup limit and make the server admit new queries only up to 90% of it. With auto and no finite limit the server refuses to start. See Memory and caches.
  • namidb-spool is disk-backed scratch space for flush and compaction (NAMIDB_SPOOL_DIR defaults to /var/tmp/namidb-spool in the image). Size it for about three times the compacted node data.
  • namidb-range-cache holds the optional persistent read cache. It is only a cache: deleting the volume makes reads cold, never loses data. NAMIDB_RANGE_CACHE_NAMESPACE must be a stable name for this deployment and bucket; the server refuses to start with an NVMe path and no name.

Run it

Terminal window
export NAMIDB_AUTH_TOKEN="$(openssl rand -hex 32)"
docker compose up -d
Terminal window
curl -s localhost:8080/v0/health
# {"status":"ok","namespace":"prod","manifest_version":0,"epoch":0,"writer":"ok",
# "memtable_bytes":0,"memory_resident_bytes":13303808,"memory_max_bytes":3865470566,
# "memory_pressure":false}
curl -s localhost:8080/v0/cypher \
-H "Authorization: Bearer $NAMIDB_AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"query": "CREATE (:Person {name: \"Alice\"}) RETURN 1 AS ok"}'
# {"columns":["ok"],"rows":[{"ok":1}],"write_outcome":{"nodes_created":1,...}}

memory_max_bytes is 90% of the 4 GiB container limit. Bolt clients connect to bolt://localhost:7687 with the same token (see Bolt).

Data layout in the bucket

With no path prefix in the URI, a single-tenant namespace lives under tenants/<ns>/ in the bucket (here tenants/prod/). Add a prefix to choose it: s3://namidb/graphs?ns=prod stores under graphs/prod/. In multi-tenant mode namespaces live at the root of the store prefix instead.

Production notes

  • Configure a bucket lifecycle rule that aborts incomplete multipart uploads after a short window. NamiDB aborts the uploads it can, but a killed process leaves parts the bucket still owns.
  • Keep exactly one server per namespace. A second server on the same store fences the first; see Multi-tenant mode.
  • Back up with the online backup endpoint to a separate bucket or prefix.

Tear down

Terminal window
docker compose down # keep the data volumes
docker compose down -v # also delete the bucket data