NornicDB

Docker platform examples ​

For the shortest path from installation to a query, use the quick start. This page contains platform-specific Docker commands and optional embedding setup.

These examples run on your computer. Set a password before starting a container:

bash
export NORNICDB_PASSWORD='replace-with-a-long-random-password'
export NORNICDB_JWT_SECRET='replace-with-at-least-32-random-characters'

The commands configure authentication explicitly. Authentication is enabled by default; see pkg/config/config.go:LoadDefaults and applyEnvVars.

Apple Silicon (Mac) ​

bash
docker run -d \
  --name nornicdb \
  -p 127.0.0.1:7474:7474 \
  -p 127.0.0.1:7687:7687 \
  -v nornicdb-data:/data \
  -e NORNICDB_AUTH="admin:${NORNICDB_PASSWORD}" \
  -e NORNICDB_AUTH_JWT_SECRET="${NORNICDB_JWT_SECRET}" \
  timothyswt/nornicdb-arm64-metal-bge:latest

NVIDIA GPU (Linux) ​

bash
docker run -d \
  --name nornicdb \
  --gpus all \
  -p 127.0.0.1:7474:7474 \
  -p 127.0.0.1:7687:7687 \
  -v nornicdb-data:/data \
  -e NORNICDB_AUTH="admin:${NORNICDB_PASSWORD}" \
  -e NORNICDB_AUTH_JWT_SECRET="${NORNICDB_JWT_SECRET}" \
  timothyswt/nornicdb-amd64-cuda-bge:latest

CPU Only (Windows/Linux) ​

bash
docker run -d \
  --name nornicdb \
  -p 127.0.0.1:7474:7474 \
  -p 127.0.0.1:7687:7687 \
  -v nornicdb-data:/data \
  -e NORNICDB_AUTH="admin:${NORNICDB_PASSWORD}" \
  -e NORNICDB_AUTH_JWT_SECRET="${NORNICDB_JWT_SECRET}" \
  timothyswt/nornicdb-amd64-cpu:latest

Verify Installation ​

bash
# Check container is running
docker ps

# Test HTTP API
curl http://localhost:7474/health

# Test with a Neo4j-compatible Cypher HTTP request
curl -u "admin:${NORNICDB_PASSWORD}" -X POST http://localhost:7474/db/nornic/tx/commit \
  -H "Content-Type: application/json" \
  -d '{"statements":[{"statement":"CREATE (n:Person {name: \"Alice\"}) RETURN n"}]}'

Access NornicDB ​

Try Your First Query ​

NornicDB's Cypher-over-HTTP flow follows the Neo4j transaction endpoint shape.

bash
# Create a node
curl -u "admin:${NORNICDB_PASSWORD}" -X POST http://localhost:7474/db/nornic/tx/commit \
  -H "Content-Type: application/json" \
  -d '{"statements":[{"statement":"CREATE (n:Person {name: \"Alice\", age: 30}) RETURN n"}]}'

# Query nodes
curl -u "admin:${NORNICDB_PASSWORD}" -X POST http://localhost:7474/db/nornic/tx/commit \
  -H "Content-Type: application/json" \
  -d '{"statements":[{"statement":"MATCH (n:Person) RETURN n.name, n.age"}]}'

# Create a relationship in one request
curl -u "admin:${NORNICDB_PASSWORD}" -X POST http://localhost:7474/db/nornic/tx/commit \
  -H "Content-Type: application/json" \
  -d '{"statements":[{"statement":"MERGE (a:Person {name: \"Alice\"}) MERGE (b:Person {name: \"Bob\"}) MERGE (a)-[:KNOWS]->(b) RETURN a, b"}]}'

Enable Semantic Search (Optional) ​

For embedding-powered search:

bash
# Stop current container
docker stop nornicdb
docker rm nornicdb

# Start with Ollama for embeddings
docker run -d \
  --name nornicdb \
  -p 127.0.0.1:7474:7474 \
  -p 127.0.0.1:7687:7687 \
  -v nornicdb-data:/data \
  -e NORNICDB_AUTH="admin:${NORNICDB_PASSWORD}" \
  -e NORNICDB_AUTH_JWT_SECRET="${NORNICDB_JWT_SECRET}" \
  -e NORNICDB_EMBEDDING_ENABLED=true \
  -e NORNICDB_EMBEDDING_PROVIDER=ollama \
  -e NORNICDB_EMBEDDING_MODEL=mxbai-embed-large \
  timothyswt/nornicdb-arm64-metal-bge:latest

# Or use docker-compose with Ollama
cat > docker-compose.yml << EOF
version: '3.8'
services:
  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama

  nornicdb:
    image: timothyswt/nornicdb-arm64-metal-bge:latest
    depends_on:
      - ollama
    ports:
      - "127.0.0.1:7474:7474"
      - "127.0.0.1:7687:7687"
    volumes:
      - nornicdb-data:/data
    environment:
      - NORNICDB_AUTH=admin:${NORNICDB_PASSWORD}
      - NORNICDB_AUTH_JWT_SECRET=${NORNICDB_JWT_SECRET}
      - NORNICDB_EMBEDDING_ENABLED=true
      - NORNICDB_EMBEDDING_PROVIDER=ollama
      - NORNICDB_EMBEDDING_API_URL=http://ollama:11434
      - NORNICDB_EMBEDDING_MODEL=mxbai-embed-large

volumes:
  ollama-data:
  nornicdb-data:
EOF

docker-compose up -d

Common CLI Commands ​

bash
# View logs
docker logs nornicdb

# Follow logs
docker logs -f nornicdb

# Access container shell
docker exec -it nornicdb sh

# Stop container
docker stop nornicdb

# Start container
docker start nornicdb

# Remove container
docker rm nornicdb

# Backup data
docker run --rm \
  -v nornicdb-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/nornicdb-backup-$(date +%Y%m%d).tar.gz -C /data .

Testing ​

bash
# Run basic functionality tests
curl -u "admin:${NORNICDB_PASSWORD}" -X POST http://localhost:7474/db/nornic/tx/commit \
  -H "Content-Type: application/json" \
  -d '{"statements":[{"statement":"RETURN 1 as test"}]}'

# Test Bolt connection (requires nc command)
nc -z localhost 7687 && echo "Bolt port open" || echo "Bolt port closed"

# Performance test
time curl -u "admin:${NORNICDB_PASSWORD}" -X POST http://localhost:7474/db/nornic/tx/commit \
  -H "Content-Type: application/json" \
  -d '{"statements":[{"statement":"MATCH (n) RETURN count(n)"}]}'

Stopping NornicDB ​

bash
# Graceful stop
docker stop nornicdb

# Remove container (keeps data)
docker rm nornicdb

# Remove data volume (deletes all data)
docker volume rm nornicdb-data

Troubleshooting ​

Container Won't Start ​

bash
# Check logs
docker logs nornicdb

# Check if ports are available
lsof -i :7474
lsof -i :7687

# Check Docker resources
docker system df

Connection Issues ​

bash
# Verify container is running
docker ps

# Check network connectivity
docker network ls
docker network inspect bridge

# Test from inside container
docker exec -it nornicdb curl http://localhost:7474/health

GPU Not Working ​

bash
# Check GPU availability (NVIDIA)
docker run --rm --gpus all nvidia/cuda:11.8-base-ubuntu20.04 nvidia-smi

# Check Metal support (macOS)
docker run --rm timothyswt/nornicdb-arm64-metal-bge:latest \
  /bin/sh -c "system_profiler SPDisplaysDataType | grep Metal"

Out of Memory ​

NornicDB uses ~1GB RAM by default. Enable low memory mode:

bash
docker run -d \
  --name nornicdb \
  -p 127.0.0.1:7474:7474 \
  -p 127.0.0.1:7687:7687 \
  -v nornicdb-data:/data \
  -e NORNICDB_LOW_MEMORY=true \
  timothyswt/nornicdb-arm64-metal-bge:latest

Next Steps ​

Search defaults: BM25 fulltext and vector ANN indexes are both enabled and built at startup for every database — today's behaviour. Multi-tenant or memory-constrained deployments can defer index builds with --search-bm25-warming=lazy / --search-vector-warming=lazy or disable indexes entirely per-database. See Per-Database Search Index Flags.

Need help? → Troubleshooting GuideProduction ready? → Docker Deployment Guide

Analytics privacy