Vearch

Deploy from the Azure Portal

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

Deploy from the Azure CLI

Replace the values in angle brackets with your own, then accept the Marketplace terms and create the VM:

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:vearch-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-resource-group> \
  --name <your-vm-name> \
  --image sac1647283583153:vearch-ubuntu-24-04:default:latest \
  --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 with 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 and writes it into the Vearch configuration. It 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 that the service is healthy

Check the services and the container:

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. The loopback binding is deliberate. The database is not directly exposed, and nginx is the only listener reachable from the network.

A liveness endpoint also answers without 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 it reports 502 if the database is stopped.

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. Scope the rule as tightly as you can to the addresses that need access:

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 no data back. Try an anonymous request and a request with a wrong password:

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

Both requests return an authentication error rather than any data. Vearch reports that error in two different ways, depending on the endpoint:

• 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. The following command 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. It is convenient for a first look, but it 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. These indexes 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. Document 2 is far away and scores 1.740000.

That ordering is the whole point of the database: it ranks 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, so you can use Vearch 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, then extend the filesystem on the VM with sudo resize2fs /dev/disk/azure/scsi1/lun0.

Managing the service

Check the service status:

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 commands 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 that 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. This 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 use 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 SecureAnyCloud. If you need help, contact us at sales@secureanycloud.com 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.

Deploy on Azure

Launch Vearch on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com