Development Setup

Get your development environment ready for NornicDB.

Prerequisites

• The Go toolchain in go.mod (currently 1.27.3)
• Node.js 24 and npm for UI/documentation builds
• Git
• Make (optional, for build shortcuts)
• Docker (optional, for containerized testing)
• curl (for downloading models)
• CGO-compatible compiler (for local LLM builds)

For contribution and validation policy, use the contribution guide. For an application using the Go library, start with embedding.

Clone Repository

git clone https://github.com/orneryd/nornicdb.git
cd nornicdb

Build from Source

Native Binary

# Basic build (with UI)
make build

# Or without make:
go build -o bin/nornicdb ./cmd/nornicdb

# Headless build (no UI, smaller binary)
make build-headless

# With local LLM support
make build-localllm

# Headless with local LLM
make build-localllm-headless

Docker Images

Model Downloads (Heimdall only)

Heimdall images require BGE-M3 embedding model (~400MB) and qwen3-0.6b LLM (~350MB):

# Download both models automatically
make download-models

# Or download individually
make download-bge    # BGE-M3 embedding model
make download-qwen   # qwen3-0.6b-Instruct LLM

# Check which models are present
make check-models

Models are downloaded from HuggingFace and saved to models/ directory.

Build Docker Images

# ARM64 (Apple Silicon)
make build-arm64-metal                    # Base (BYOM)
make build-arm64-metal-bge                # With BGE embeddings
make build-arm64-metal-bge-heimdall       # With BGE + Heimdall AI (auto-downloads models)
make build-arm64-metal-headless           # Headless (no UI)

# AMD64 CUDA (NVIDIA GPU)
make build-amd64-cuda                     # Base (BYOM)
make build-amd64-cuda-bge                 # With BGE embeddings
make build-amd64-cuda-bge-heimdall        # With BGE + Heimdall AI (auto-downloads models)
make build-amd64-cuda-headless            # Headless (no UI)

# AMD64 CPU-only (no GPU, embeddings disabled)
make build-amd64-cpu                      # Minimal
make build-amd64-cpu-headless             # Minimal headless

# Build all variants for current architecture
make build-all

Deploy to Registry

# Deploy specific image (build + push)
make deploy-arm64-metal-bge-heimdall

# Deploy all variants for current architecture
make deploy-all

Cross-Compilation

Build native binaries for other platforms from macOS:

# Linux servers
make cross-linux-amd64        # x86_64 (VPS, cloud)
make cross-linux-arm64        # ARM64 (Graviton, Jetson)

# Raspberry Pi
make cross-rpi                # Pi 4/5 (64-bit)
make cross-rpi32              # Pi 2/3 (32-bit)
make cross-rpi-zero           # Pi Zero (ARMv6)

# Windows
make cross-windows            # CPU-only build

# Build all platforms
make cross-all

Note: Cross-compiled binaries are pure Go (no CGO), so Metal/CUDA acceleration and local LLM support are not available.

Run Tests

# All tests
go test ./...

# With coverage
go test -cover ./...

# Specific package
go test ./pkg/nornicdb/...

Start Development Server

# Default settings (localhost:7474)
./bin/nornicdb serve --data-dir=./dev-data

# With auth disabled for easier development
./bin/nornicdb serve --data-dir=./dev-data --no-auth

# Custom ports
./bin/nornicdb serve --http-port=8080 --bolt-port=8687

Environment Variables

Core Settings

Variable	Description	Default
NORNICDB_DATA_DIR	Data directory	./data
NORNICDB_HTTP_PORT	HTTP API port	7474
NORNICDB_BOLT_PORT	Bolt port	7687
NORNICDB_AUTH	Set to none to disable, or user/pass to enable	none (auth off)
NORNICDB_AUTH_JWT_SECRET	JWT secret (min 32 characters)	Required for auth
NORNICDB_HEADLESS	Disable embedded UI routes and browser IDEs; core APIs remain available	false

Embedding & AI Features

Variable	Description	Default
NORNICDB_EMBEDDING_PROVIDER	Embedding provider	local
NORNICDB_EMBEDDING_MODEL	Model path/name	models/bge-m3.gguf
NORNICDB_HEIMDALL_ENABLED	Enable Heimdall AI	false
NORNICDB_HEIMDALL_MODEL	Heimdall LLM model	models/qwen3-0.6b-instruct-q4_k_m.gguf
NORNICDB_SEARCH_RERANK_ENABLED	Enable Stage-2 search reranking	false
NORNICDB_SEARCH_RERANK_PROVIDER	Reranker backend: local, ollama, openai, http	local
NORNICDB_SEARCH_RERANK_MAX_DOCUMENT_CHARS	Maximum characters per rerank candidate (title/name + matched chunk with neighbours); …_BYTES deprecated	2048
NORNICDB_PLUGINS_DIR	APOC plugins directory	apoc/built-plugins

IDE Setup

VS Code

Recommended extensions:

• Go (official)
• Go Test Explorer
• GitLens

// .vscode/settings.json
{
  "go.lintTool": "golangci-lint",
  "go.testFlags": ["-v"],
  "editor.formatOnSave": true
}

Git Hooks

Install the repository's tracked Git hooks after cloning:

make install-hooks

The pre-commit hook auto-formats staged Go files with gofmt -w -s before the commit is written, so formatting fixes are included in the commit instead of being left behind as dangling working tree changes.

GoLand

1. Open project root
2. Set GOPATH to project directory
3. Enable "Go Modules" in Preferences

Project Structure

nornicdb/
├── cmd/nornicdb/     # CLI application
├── pkg/
│   ├── nornicdb/     # Core database
│   ├── server/       # HTTP server
│   ├── storage/      # Storage engines
│   ├── auth/         # Authentication
│   ├── audit/        # Audit logging
│   ├── gpu/          # GPU acceleration
│   └── heimdall/     # AI assistant
├── apoc/
│   ├── plugin-src/   # Plugin source code
│   └── built-plugins/ # Compiled plugins (.so)
├── docker/           # Docker files
├── models/           # LLM/embedding models
├── ui/               # Web UI (Svelte)
└── docs/             # Documentation

APOC Plugin Development

NornicDB supports dynamic Go plugins (Linux/macOS only):

# Build APOC plugin
make plugins

# Run with plugins
NORNICDB_PLUGINS_DIR=apoc/built-plugins ./bin/nornicdb serve

# Clean plugins
make plugins-clean

See APOC Plugin Guide for creating custom functions.

Heimdall AI Assistant

Enable the built-in AI assistant for natural language database interactions:

# Ensure models are present
make check-models

# Download if missing
make download-models

# Run with Heimdall enabled
NORNICDB_HEIMDALL_ENABLED=true \
NORNICDB_HEIMDALL_MODEL=models/qwen3-0.6b-instruct-q4_k_m.gguf \
./bin/nornicdb serve

Access Bifrost (Heimdall UI) at http://localhost:7474/bifrost

See Heimdall AI Assistant Guide for details.

Next Steps

• Testing Guide - How to write tests
• Code Style - Code conventions
• Heimdall Plugins - Create custom AI actions
• APOC Plugins - Extend Cypher with custom functions
• Contributing - Contribution process