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®ion=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-initstart the object store and create thenamidbbucket. The ports are bound to127.0.0.1; publish them more widely only behind your own access controls, and change the default MinIO credentials.NAMIDB_STOREpoints the server at the bucket.endpoint=is the in-network MinIO address,allow_http=trueallows plain HTTP to it, andregion=is required by the S3 client (any value works for MinIO).mem_limit+NAMIDB_MEMORY_MAX_BYTES=autogive the process a hard cgroup limit and make the server admit new queries only up to 90% of it. Withautoand no finite limit the server refuses to start. See Memory and caches.namidb-spoolis disk-backed scratch space for flush and compaction (NAMIDB_SPOOL_DIRdefaults to/var/tmp/namidb-spoolin the image). Size it for about three times the compacted node data.namidb-range-cacheholds the optional persistent read cache. It is only a cache: deleting the volume makes reads cold, never loses data.NAMIDB_RANGE_CACHE_NAMESPACEmust be a stable name for this deployment and bucket; the server refuses to start with an NVMe path and no name.
Run it
export NAMIDB_AUTH_TOKEN="$(openssl rand -hex 32)"docker compose up -dcurl -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
docker compose down # keep the data volumesdocker compose down -v # also delete the bucket data