Skip to content
NamiDB NamiDB

Self-host with Docker Compose

A copy-paste self-hosted NamiDB stack that runs anywhere Docker Compose runs. MinIO holds the bucket, namidb-server serves the namespace over an authenticated REST API.

docker-compose.yml

services:
  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    volumes:
      - minio-data:/data
    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-server:0.3        # built from crates/namidb-server/Dockerfile
    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_LISTEN: "0.0.0.0:8080"
      NAMIDB_AUTH_TOKEN: "${NAMIDB_AUTH_TOKEN:?set NAMIDB_AUTH_TOKEN in your env}"
      NAMIDB_FLUSH_INTERVAL: "30s"
      AWS_ACCESS_KEY_ID: "minioadmin"
      AWS_SECRET_ACCESS_KEY: "minioadmin"
    ports:
      - "8080:8080"


volumes:
  minio-data: {}

Bring it up

  1. Build the server image (one-time, from the engine repo root):

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

  2. Generate an auth token:

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

  3. Start the stack:

    Terminal window
    docker compose up -d

  4. Smoke-test:

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

    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\"}) RETURN a.name AS name"}' \
      | jq .

That’s it. A graph database, your data on disk in MinIO, an authenticated REST API on :8080.

Move it to a real cloud

Swap one env var. Everything else stays:

environment:
  NAMIDB_STORE: "s3://my-bucket?ns=prod&region=us-east-1"
  # NAMIDB_STORE: "s3://my-bucket?ns=prod&endpoint=https://<ACCOUNT_ID>.r2.cloudflarestorage.com&region=auto"
  # NAMIDB_STORE: "gs://my-bucket?ns=prod"
  # NAMIDB_STORE: "az://acct/container?ns=prod"

Same engine, same Docker image. Object storage is the source of truth.

See also