Installation

Goal: get an Ahnlich DB server running on your machine. Once it's running and answers PING with PONG, you're ready to create stores and run searches.

There are three ways to install it — pick whichever suits you:

However you install it, you finish the same way: a server running on your machine that answers PING. From there every command works the same.

Option	Best if you…	Where
Download a binary	just want it running fast	below
Docker	prefer an isolated, reproducible setup	below
Build from source	are developing on Ahnlich itself	CLI install → from source

The rest of this page walks through each option, then a quick smoke test at the end.

1. Download Binaries

Prebuilt binaries are available from GitHub Releases.

wget is not installed on macOS by default, so the examples below use curl (built in). Check your Mac's chip with uname -m — arm64 means Apple Silicon, x86_64 means Intel.

Download the binary

macOS — Apple Silicon (M1/M2/M3/M4):

$curl -L -O "https://github.com/deven96/ahnlich/releases/download/bin%2Fdb%2F0.2.2/aarch64-apple-darwin-ahnlich-db.tar.gz"

macOS — Intel:

$curl -L -O "https://github.com/deven96/ahnlich/releases/download/bin%2Fdb%2F0.2.2/x86_64-apple-darwin-ahnlich-db.tar.gz"

Linux — x86_64:

$curl -L -O "https://github.com/deven96/ahnlich/releases/download/bin%2Fdb%2F0.2.2/x86_64-unknown-linux-gnu-ahnlich-db.tar.gz"

Linux — ARM64:

$curl -L -O "https://github.com/deven96/ahnlich/releases/download/bin%2Fdb%2F0.2.2/aarch64-unknown-linux-gnu-ahnlich-db.tar.gz"

Extract the archive (use the file you downloaded):

$tar -xvzf *-ahnlich-db.tar.gz

Run the binary:

$./ahnlich-db

On macOS, if Gatekeeper blocks the unsigned binary, clear the quarantine flag first: xattr -d com.apple.quarantine ./ahnlich-db

2. Using Docker

Ahnlich DB also ships as a Docker image:

docker pull ghcr.io/deven96/ahnlich-db:latest

Run with:

docker run --rm -p 1369:1369 \
  --name ahnlich-db \
  ghcr.io/deven96/ahnlich-db:latest \
  ahnlich-db run --port 1369

3. Example Docker Compose

You can orchestrate Ahnlich DB with docker-compose.

Basic (with tracing enabled):

services:
  ahnlich_db:
    image: ghcr.io/deven96/ahnlich-db:latest
    command: >
      "ahnlich-db run --host 0.0.0.0
      --enable-tracing
      --otel-endpoint http://jaeger:4317"
    ports:
      - "1369:1369"

  # Optional Jaeger service for tracing
  jaeger:
    image: jaegertracing/all-in-one:${JAEGER_VERSION:-latest}
    ports:
      - "16686:16686"
      - "4317:4317"
      - "4318:4318"

With Persistence:

services:
  ahnlich_db:
    image: ghcr.io/deven96/ahnlich-db:latest
    command: >
      "ahnlich-db run --host 0.0.0.0
      --enable-persistence --persist-location /root/.ahnlich/data/db.dat
      --persistence-interval 300"
    ports:
      - "1369:1369"
    volumes:
      - "./data/:/root/.ahnlich/data" # Persistence Location

Configuration Options

Ahnlich DB can be customized using runtime flags:

• --host <ip> - Specify listening host (default: 0.0.0.0).

• --port <port> - Specify server port (default: 1369).

• --enable-tracing - Enable telemetry tracing with OpenTelemetry.

• --otel-endpoint <url> - OpenTelemetry endpoint (e.g., Jaeger).

• --enable-persistence - Enable snapshot persistence to disk.

• --persist-location <path> - File location for persistence (default: ~/.ahnlich/data/db.dat).

• --persistence-interval <seconds> - Interval in seconds between snapshots.

Quick Start Example

Start a simple database:

./ahnlich-db run --host 0.0.0.0 --port 1369

Create a store:

CREATESTORE my_store DIMENSION 2

Insert a vector with metadata:

SET [0.2, 0.1] WITH { "page": "home" } IN my_store

Run a similarity search:

GETSIMN 2 WITH [0.2, 0.1] USING cosinesimilarity IN my_store WHERE (page != hidden)