Saltearse al contenido

Docker + MinIO

Esta receta ejecuta namidb-server contra un bucket de MinIO con Docker Compose. Refleja el docker-compose.yml del repositorio del motor y usa la imagen oficial, así que no se compila nada localmente.

Cualquier servidor compatible con S3 que aplique escrituras condicionales (If-None-Match: *) funciona igual: cambia la imagen y el endpoint= del URI del store. Consulta Object stores.

El archivo Compose

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: {}

Para qué sirve cada parte:

  • minio / bucket-init inician el object store y crean el bucket namidb. Los puertos están vinculados a 127.0.0.1; publícalos de forma más amplia solo detrás de tus propios controles de acceso, y cambia las credenciales por defecto de MinIO.
  • NAMIDB_STORE apunta el servidor al bucket. endpoint= es la dirección de MinIO dentro de la red, allow_http=true permite HTTP plano hacia ella, y region= es obligatorio para el cliente S3 (con MinIO funciona cualquier valor).
  • mem_limit + NAMIDB_MEMORY_MAX_BYTES=auto dan al proceso un límite estricto de cgroup y hacen que el servidor admita consultas nuevas solo hasta el 90% de ese límite. Con auto y sin un límite finito, el servidor se niega a arrancar. Consulta Memoria y cachés.
  • namidb-spool es espacio temporal en disco para el flush y la compactación (NAMIDB_SPOOL_DIR vale /var/tmp/namidb-spool por defecto en la imagen). Dimensiónalo para unas tres veces los datos de nodos compactados.
  • namidb-range-cache contiene la caché de lectura persistente opcional. Es solo una caché: borrar el volumen hace que las lecturas empiecen en frío, nunca pierde datos. NAMIDB_RANGE_CACHE_NAMESPACE debe ser un nombre estable para este despliegue y este bucket; el servidor se niega a arrancar con una ruta NVMe y sin nombre.

Ejecutarlo

Ventana de terminal
export NAMIDB_AUTH_TOKEN="$(openssl rand -hex 32)"
docker compose up -d
Ventana de terminal
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 es el 90% del límite de 4 GiB del contenedor. Los clientes Bolt se conectan a bolt://localhost:7687 con el mismo token (consulta Bolt).

Organización de los datos en el bucket

Sin prefijo de ruta en el URI, un namespace single-tenant vive bajo tenants/<ns>/ en el bucket (aquí tenants/prod/). Agrega un prefijo para elegirlo: s3://namidb/graphs?ns=prod guarda bajo graphs/prod/. En modo multi-tenant los namespaces viven, en cambio, en la raíz del prefijo del store.

Notas para producción

  • Configura una regla de ciclo de vida del bucket que aborte las cargas multipart incompletas después de un período corto. NamiDB aborta las cargas que puede, pero un proceso que se mata deja partes que el bucket sigue conservando.
  • Mantén exactamente un servidor por namespace. Un segundo servidor sobre el mismo store bloquea (fencing) al primero; consulta Modo multi-tenant.
  • Haz backups con el endpoint de backup en línea hacia un bucket o prefijo separado.

Desmontar

Ventana de terminal
docker compose down # keep the data volumes
docker compose down -v # also delete the bucket data