Installation

VeltrixDB can be installed four ways: a Docker image for local testing, a source build for development, a Helm chart for Kubernetes, or the Kubernetes Operator for fully managed clusters.

Docker

The fastest way to try VeltrixDB. The published image requires no build step:

docker run -p 9000:9000 ghcr.io/veltrixdb/veltrixdb:latest

This starts a single standalone node listening on 9000. It's suitable for local development and protocol testing, not for production NVMe throughput — for that, run on bare metal or Kubernetes with real local NVMe disks attached.

Build from source

Requires Go 1.19+. The Go layer builds and runs on macOS and Linux; the optional C++ acceleration layer (io_uring, ART index, NUMA pinning) is only active on Linux.

git clone https://github.com/VeltrixDB/veltrixdb
cd veltrixdb
go build ./...
go run ./cmd/server -addr :9000 -data ./dev-data -cache 256

To build the standalone binary and additional tooling (operator CLI, backup tool):

go build -o veltrix ./cmd/veltrix        # cluster CLI: status, nodes, top, put/get, backup
go build -o veltrixdb-backup ./cmd/backup # backup/restore tool

Run the test suite before contributing changes:

go test ./...            # unit tests
./tests/e2e/run_all.sh   # e2e tests (requires a running server)
./scripts/bench.sh       # benchmark with pass/fail gates

Helm chart

The Helm chart deploys a full production topology on Kubernetes: a StatefulSet with stable per-node hostnames, an nvme-prep DaemonSet that formats and prepares local NVMe disks, a StorageClass for local NVMe PersistentVolumes, a ServiceMonitor for Prometheus scraping, a PodDisruptionBudget, and 22 PrometheusRule alerts covering slow disks, GC emergencies, scrub corruption, and replication lag.

helm repo add veltrixdb https://charts.veltrixdb.io
helm repo update

helm install veltrixdb veltrixdb/veltrixdb \
  --namespace veltrixdb \
  --create-namespace

Verify the deployment:

kubectl get pv | grep local-nvme
kubectl get pods -n veltrixdb -l app.kubernetes.io/name=veltrixdb
kubectl exec -n veltrixdb veltrixdb-0 -- sh -c 'echo PING | nc 127.0.0.1 9000'
# Expected: PONG

See the Helm Chart reference for the full values table, including cache sizing, TLS, encryption, quotas, and raw block-device VLog options.

Kubernetes Operator

The Operator manages VeltrixDB clusters through a VeltrixCluster Custom Resource. It creates and owns the StatefulSet, Services, ConfigMap, and PVCs; automatically reshards when replica count changes; self-heals failed pods; and performs rolling upgrades.

Deploy the NVMe mount keeper first — it ensures real NVMe XFS filesystems are mounted at the PV source paths before kubelet binds them into the pod (skipping this causes ENOSPC on the first WAL write):

kubectl apply -f config/manager/nvme-mount-keeper.yaml
kubectl rollout status daemonset/nvme-mount-keeper -n veltrixdb

Install the CRDs, then deploy the operator:

kubectl apply -f config/crd/bases/
kubectl apply -f config/manager/manager.yaml

Create a cluster:

apiVersion: veltrixdb.io/v1alpha1
kind: VeltrixCluster
metadata:
  name: my-cluster
  namespace: veltrixdb
spec:
  replicas: 3
  image: veltrixdb/veltrixdb:1.0.0
  disksPerNode: 8
  cacheSizeMB: 262144
  walFlushWindowMs: 10
  vlogFlushWindowMs: 10

kubectl apply -f veltrixcluster.yaml
kubectl get veltrixcluster -n veltrixdb

See the Kubernetes Operator reference for the full spec, including at-rest encryption, audit logging, per-namespace quotas, the admin API/UI surface, and the optional chaos-engineering sidecar.

gcloud container node-pools create veltrixdb-pool \
  --cluster=my-cluster \
  --zone=us-central1-a \
  --machine-type=n2-highmem-64 \
  --num-nodes=3 \
  --local-ssd-count=8 \
  --local-ssd-interface=NVME \
  --disk-size=100GB

What gets installed (Helm and Operator)

Both the Helm chart and the Operator provision the same core set of Kubernetes resources:

The Operator additionally handles auto-reshard on replica-count changes and self-healing pod replacement as part of its reconcile loop.