Deployment

Three supported deployment shapes: a single binary on a host, a single-container Docker Compose stack, and a 3-node high-availability cluster behind a Traefik load balancer.

Single binary

The release binary embeds the default ONNX model and runtime. No system packages, no model downloads. Drop it on a host and run.

# Download the binary for your platform from the GraphANN customer
# portal (issued with your commercial licence — request access at /contact).
# Linux x86_64 example:
curl -LO https://downloads.graphann.com/graphann/v0.9.0/graphann-linux-amd64
chmod +x graphann-linux-amd64
mv graphann-linux-amd64 /usr/local/bin/graphann

graphann serve \
  --data-dir /var/lib/graphann \
  --embedding-server local_onnx \
  --port 38888

systemd unit

For long-running deployments on a Linux host, register a unit at /etc/systemd/system/graphann.service.

[Unit]
Description=GraphANN vector database
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=graphann
Group=graphann
ExecStart=/usr/local/bin/graphann serve \
  --data-dir /var/lib/graphann \
  --embedding-server local_onnx \
  --port 38888
Restart=on-failure
RestartSec=5
LimitNOFILE=65536
ProtectSystem=strict
ReadWritePaths=/var/lib/graphann
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Then systemctl daemon-reload && systemctl enable --now graphann.

Docker Compose

Single-container layout. The bundled docker-compose.yaml mounts a named volume for data and exposes port 38888.

# From the graphann repo root:
docker compose up -d

# Logs
docker compose logs -f graphann

# Stop
docker compose down

# Wipe data
docker compose down -v

The compose file routes the embedding server through environment variables. Defaults assume Ollama on the host (host.docker.internal:11434); switch to local_onnx for full self-containment.

# .env or shell exports
EMBEDDING_SERVER=local_onnx
EMBEDDING_MODEL=nomic-embed-text:v1.5
# For Ollama on host:
# EMBEDDING_SERVER=ollama
# OLLAMA_URL=http://host.docker.internal:11434
# For LM Studio on host:
# EMBEDDING_SERVER=lmstudio
# LMSTUDIO_URL=http://host.docker.internal:1234/v1

3-node high-availability cluster

docker-compose.cluster.yaml provisions three GraphANN™ nodes across simulated zones (zone-a, zone-b, zone-c) with replication factor 3, fronted by Traefik. Raft handles consensus; gossip handles membership and failure detection; shards replicate across zones; anti-entropy repair runs in the background.

# Boot all 3 nodes + Traefik + Prometheus
docker compose -f docker-compose.cluster.yaml up --build -d

# Membership check
curl http://localhost:38891/cluster/members | jq

# Kill node 2 — cluster keeps serving via node 1 + 3
docker compose -f docker-compose.cluster.yaml stop node2

# Bring it back — anti-entropy repair catches it up
docker compose -f docker-compose.cluster.yaml start node2

Endpoints after up:

  • http://localhost:38888: load-balanced API (full /v1/...).
  • http://localhost:38881, :38882, :38883: direct per-node API access (bypasses LB).
  • http://localhost:38891/cluster/members: node-1 sidecar for cluster introspection.
  • http://localhost:8080: Traefik dashboard.
  • http://localhost:9090: Prometheus.

Sizing

Replication factor 3 means each shard lives on 3 nodes. A 3-node cluster tolerates 1 node failure for reads and writes. Larger clusters can tolerate more; set --rf at boot. Zones drive shard placement: replicas are spread across distinct zones first, then within.

Production checklist

  • Pin a release tag, not latest.
  • Mount /data on durable storage (ext4 / xfs / NFS).
  • Front the API with TLS termination at the proxy. The server speaks plain HTTP.
  • Scrape /metrics from Prometheus. Alert on graphann_search_latency_seconds p99 and on the up series for each node.
  • Set per-tenant rate limits at the proxy until the in-server limiter ships.
  • Capture log lines as JSON to your log pipeline; the server logs structured JSON via slog.