Vearch on Ubuntu 24.04 on Azure User Guide

Overview

This image runs Vearch on Ubuntu 24.04 on Azure, an open source vector database for similarity search over embeddings. Vearch stores high dimensional vectors alongside ordinary scalar fields and returns nearest neighbours in milliseconds, which is what lets an application search by meaning rather than by keyword. It is commonly used as the retrieval layer for retrieval augmented generation, semantic and visual search, recommendation and near duplicate detection.

Vearch is a distributed database by design, with three roles: a master that owns schema and cluster metadata, a router that serves the REST API and merges results, and a partition server that stores and indexes the documents. This image ships the vendor's documented standalone mode, in which all three roles run co located in a single process on one machine. There is no cluster to assemble, no etcd to operate and no Kubernetes required: the whole database is this one virtual machine, and it is answering queries as soon as it boots.

This is a headless database. There is no web login page. Everything is done through a JSON REST API, which the image publishes over HTTPS on port 443. Every request is authenticated as the root user using HTTP Basic authentication, and on the first boot of your virtual machine a one shot service generates a root password unique to that machine, writes it to a root only file, and issues a TLS certificate for that machine. The upstream default password never exists on your VM.

The cluster metadata and the vector data both live on a dedicated, independently resizable Azure data disk mounted at /var/lib/vearch, so the stateful tier sits on durable storage rather than the operating system disk and can be grown or snapshotted independently.

What is included:

• Vearch 3.5.9 from the official vearch/vearch container image, pinned by digest
• Docker Engine and the Compose plugin from the official Docker repository
• nginx terminating TLS on port 443 in front of the Vearch router
• A per VM root credential and a per VM self signed TLS certificate, both generated on first boot
• A dedicated 30 GiB Azure data disk mounted at /var/lib/vearch
• Ubuntu 24.04 LTS, fully patched at build time, with unattended security updates left enabled

Deploy from the Azure Portal

1. In the Azure Portal choose Create a resource, then search for the cloudimg Vearch image and select Create.
2. Pick your subscription, resource group and region.
3. Choose a virtual machine size. Standard_B2ms (2 vCPU, 8 GiB) is the recommended minimum. Vearch holds its vector indexes in memory, so memory is the resource that matters most; choose a larger size if you intend to load millions of vectors.
4. Under Administrator account select SSH public key and supply your public key. The default administrator username is azureuser.
5. Under Inbound port rules allow SSH (22) only. You will add port 443 deliberately in a later step.
6. Select Review + create, then Create.

Deploy from the Azure CLI

Replace the placeholder values with your own before running this.

az vm create \
  --resource-group <your-resource-group> \
  --name <your-vm-name> \
  --image <the-cloudimg-vearch-image-urn> \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard

Connect over SSH

From your workstation, connect as azureuser using the private key that matches the public key you supplied.

ssh azureuser@<your-vm-ip>

First boot and your per VM credentials

On the first boot of your virtual machine, vearch-firstboot.service runs once. It generates a random root password unique to that machine, writes it into the Vearch configuration, issues a self signed TLS certificate carrying that machine's addresses, and writes everything to /root/vearch-credentials.txt with 0600 permissions so only root can read it. Vearch itself is deliberately blocked from starting until this has completed, so the database can never come up with a default credential.

Read your credentials on the VM:

sudo ls -l /root/vearch-credentials.txt
sudo cat /root/vearch-credentials.txt

The password in that file is the value referred to as <your-root-password> throughout the rest of this guide.

Check the service is healthy

sudo systemctl is-active vearch.service
sudo systemctl is-active nginx.service
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

The container should report (healthy), and you should see the Vearch router published on 127.0.0.1:9001. That loopback binding is deliberate: the database is not directly exposed, and nginx is the only listener reachable from the network.

There is also a liveness endpoint that needs no credentials:

curl -ks -o /dev/null -w 'healthz HTTP %{http_code}\n' https://127.0.0.1/healthz

This returns 200 only while the database is actually serving. It proxies to the Vearch router rather than answering from nginx alone, so if the database were stopped it would report 502 instead.

Open port 443 to reach the database

The deployment security group opens SSH only. To reach Vearch from your application, add an inbound rule for TCP 443, scoped as tightly as you can to the addresses that need it.

az network nsg rule create \
  --resource-group <your-resource-group> \
  --nsg-name <your-nsg-name> \
  --name allow-vearch-https \
  --priority 1010 \
  --protocol Tcp \
  --destination-port-ranges 443 \
  --source-address-prefixes <your-office-or-app-cidr> \
  --access Allow

Authentication and TLS

Every API call is authenticated as root over HTTPS. An unauthenticated caller gets nothing back.

curl -ks https://127.0.0.1/dbs
curl -ks -u root:definitely-wrong https://127.0.0.1/dbs

Both of those return an authentication error rather than any data. Vearch reports that error in two different ways depending on the endpoint, and it is worth knowing which to expect:

• The document endpoints under /document/ answer an unauthenticated caller with HTTP 401.
• The cluster and schema endpoints such as /dbs and /users are proxied through the router, so they answer with HTTP 200 carrying {"code":3,"msg":"auth header ..."} in the JSON body. No data is returned in either case; only an authenticated caller ever receives "code":0 with a data payload.

Now authenticate properly. This reads the password straight from the credentials file so no secret is typed on the command line:

PASS=$(sudo sed -n 's/^vearch.root.pass=//p' /root/vearch-credentials.txt)
curl -ks -u "root:$PASS" https://127.0.0.1/dbs

That returns {"code":0,...,"data":[]} on a fresh machine, because no databases exist yet.

The certificate is self signed and generated for your machine specifically, so a client must either trust it or skip verification. To trust it, copy /etc/ssl/certs/vearch-selfsigned.crt from the VM to your client and point your HTTP client at it as a CA bundle. The -k flag used throughout this guide skips verification instead, which is convenient for a first look but should not be your long term choice for production traffic.

Create a database and a space

A database is a namespace, and a space is the equivalent of a table: it defines the scalar fields and the vector field, including the vector's dimension and index type.

Create a database named demo:

PASS=$(sudo sed -n 's/^vearch.root.pass=//p' /root/vearch-credentials.txt)
curl -ks -u "root:$PASS" -X POST https://127.0.0.1/dbs/demo

Now create a space named items with one integer field and one four dimensional vector field:

PASS=$(sudo sed -n 's/^vearch.root.pass=//p' /root/vearch-credentials.txt)
curl -ks -u "root:$PASS" -X POST https://127.0.0.1/dbs/demo/spaces \
  -H 'Content-Type: application/json' \
  -d '{"name":"items","partition_num":1,"replica_num":1,"fields":[{"name":"field_int","type":"integer"},{"name":"field_vector","type":"vector","dimension":4,"store_type":"MemoryOnly","index":{"name":"gamma","type":"FLAT","params":{"metric_type":"L2"}}}]}'

Two settings matter on a single machine deployment:

• replica_num must be 1. Vearch defaults to three replicas, which a standalone deployment with one partition server cannot satisfy, and space creation fails if you leave the default.
• partition_num should be 1 for the same reason.

The dimension must match the embedding model you intend to use. The example uses 4 so it is easy to read; a real deployment would use something like 768 or 1536. The FLAT index is exact and needs no training, which makes it ideal for getting started and for small collections. Vearch also supports IVFFLAT, IVFPQ and HNSW for larger datasets, and those require a training threshold to be reached before the index builds.

Insert vectors and run a similarity search

Upsert three documents. Each carries an id, a scalar and a four dimensional vector:

PASS=$(sudo sed -n 's/^vearch.root.pass=//p' /root/vearch-credentials.txt)
curl -ks -u "root:$PASS" -X POST https://127.0.0.1/document/upsert \
  -H 'Content-Type: application/json' \
  -d '{"db_name":"demo","space_name":"items","documents":[{"_id":"1","field_int":1,"field_vector":[0.10,0.20,0.30,0.40]},{"_id":"2","field_int":2,"field_vector":[0.90,0.90,0.90,0.90]},{"_id":"3","field_int":3,"field_vector":[0.11,0.21,0.31,0.41]}]}'

Now search for the nearest neighbours of the query vector [0.10, 0.20, 0.30, 0.40]:

PASS=$(sudo sed -n 's/^vearch.root.pass=//p' /root/vearch-credentials.txt)
curl -ks -u "root:$PASS" -X POST https://127.0.0.1/document/search \
  -H 'Content-Type: application/json' \
  -d '{"db_name":"demo","space_name":"items","vectors":[{"field":"field_vector","feature":[0.10,0.20,0.30,0.40]}],"fields":["field_int"],"vector_value":false,"limit":3}' \
  > /tmp/vearch-search.json
python3 -c 'import json; r=json.load(open("/tmp/vearch-search.json")); [print("  _id=%s  _score=%.6f  field_int=%s" % (d["_id"], d.get("_score",0), d.get("field_int"))) for g in r["data"]["documents"] for d in g]'

The results come back ordered by distance. Document 1 is the exact match and scores 0.000000, document 3 is very close and scores 0.000400, and document 2 is far away and scores 1.740000. That ordering is the whole point of the database: it ranked by vector distance, not by insertion order.

When you are finished experimenting, remove the space and the database:

PASS=$(sudo sed -n 's/^vearch.root.pass=//p' /root/vearch-credentials.txt)
curl -ks -u "root:$PASS" -X DELETE https://127.0.0.1/dbs/demo/spaces/items
curl -ks -u "root:$PASS" -X DELETE https://127.0.0.1/dbs/demo

Connect from your application

Vearch publishes official clients for Python, Go, Java and Rust, and it integrates with common AI application frameworks. From a remote machine, point your client at your VM over HTTPS and authenticate as root.

Using the Python SDK:

pip install vearch

import requests

BASE = "https://<your-vm-ip>"
AUTH = ("root", "<your-root-password>")

# verify=False skips the self signed certificate check. In production, pass
# verify="/path/to/vearch-selfsigned.crt" instead so the connection is verified.
r = requests.post(
    f"{BASE}/document/search",
    auth=AUTH,
    verify=False,
    json={
        "db_name": "demo",
        "space_name": "items",
        "vectors": [{"field": "field_vector", "feature": [0.1, 0.2, 0.3, 0.4]}],
        "fields": ["field_int"],
        "vector_value": False,
        "limit": 3,
    },
)
print(r.json())

The same request shape works from any HTTP client, which is what makes Vearch straightforward to use from a language that has no dedicated SDK.

Where your data lives

All state is on the dedicated Azure data disk mounted at /var/lib/vearch:

df -h /var/lib/vearch
sudo ls -l /var/lib/vearch

• /var/lib/vearch/data holds the cluster metadata and the partition server's documents and indexes
• /var/lib/vearch/logs holds the Vearch server logs

Because this is a separate managed disk, you can snapshot it, back it up or grow it independently of the operating system disk. To grow it, resize the disk in the Azure Portal and then extend the filesystem on the VM with sudo resize2fs /dev/disk/azure/scsi1/lun0.

Managing the service

Check status, and restart or stop the database:

sudo systemctl is-active vearch.service
sudo systemctl is-enabled vearch.service

To restart the database, run sudo systemctl restart vearch.service. To stop it, run sudo systemctl stop vearch.service. Both act on the whole standalone container.

To read recent server output, run sudo docker logs --tail 50 vearch-standalone. The Vearch server also writes its own logs under /var/lib/vearch/logs.

Troubleshooting

The API does not respond from my application. Confirm the health endpoint answers on the VM itself with curl -ks -o /dev/null -w '%{http_code}' https://127.0.0.1/healthz. If that returns 200, the database is fine and the problem is network reachability: check that your Network Security Group allows inbound TCP 443 from your client address.

My client reports a certificate error. That is expected with the per VM self signed certificate. Either trust /etc/ssl/certs/vearch-selfsigned.crt on the client, or disable verification for a first test.

Creating a space fails. The most common cause on a single machine is leaving replica_num at its default of three. Set "replica_num": 1 and "partition_num": 1.

A search returns no documents. Indexing is asynchronous, so a search issued immediately after an upsert can return before the documents are visible. Wait a second and retry. If you are using IVFPQ or HNSW rather than FLAT, the index does not build until the training threshold is reached, and searches fall back accordingly.

I have lost the root password. It exists only in /root/vearch-credentials.txt on your VM. Read it with sudo cat /root/vearch-credentials.txt.

Support

This image is supported by cloudimg. If you need help, contact us at support@cloudimg.co.uk and include the Azure region, the VM size and the output of sudo systemctl is-active vearch.service.

Upstream project documentation is at vearch.readthedocs.io and the source is at github.com/vearch/vearch. Vearch is licensed under the Apache License 2.0.