Qdrant

Qdrant 1.18 vector database — similarity search for embeddings (RAG, recommendations, semantic search). Runs as a single node, or as a distributed cluster when you add replicas. Secured with an API key and reachable only over your private network by default.

Configuration

services:
  vectors:
    package: qdrant

That's a complete single-node setup — the API key is auto-generated on the first managed apply and reused forever after. To pin your own key (for example from an environment variable):

services:
  vectors:
    package: qdrant
    config:
      api_key: "${QDRANT_API_KEY}"

To run a cluster, add replicas:

services:
  vectors:
    package: qdrant
    replicas: 2   # 3 nodes total: the first peer + 2 joining peers

Parameters

Parameter	Required	Default	Description
api_key	Yes	auto-generated	The key clients must send in the api-key header
replicas	No	0	Additional cluster nodes beyond the first
version	No	1.18.3	Qdrant release to install. The default installs checksum-verified; other versions download unverified
bind_public	No	false	Listen on all interfaces instead of the private/overlay IP. A footgun — only enable if you know the ports are firewalled
keep_daily_backups	No	5	Number of daily backups to retain
keep_weekly_backups	No	1	Number of weekly backups to retain
keep_monthly_backups	No	1	Number of monthly backups to retain

Connection

Qdrant serves HTTP (REST + JSON) on 6333 and gRPC on 6334, bound to the private/overlay address so only your other servers can reach it. Every request carries the API key in the api-key header:

curl -H "api-key: $QDRANT_API_KEY" http://<private-ip>:6333/collections

The official client libraries take the same key:

from qdrant_client import QdrantClient
client = QdrantClient(host="<private-ip>", port=6333, api_key="...")

The auto-generated key is stored with your project's state and shown (masked) in the dashboard's Configuration panel for the service.

Clustering

Set replicas and managed apply grows the service into a real distributed cluster:

• The first node is the cluster's founding peer. Its configuration never changes when nodes join, so scale-ups don't restart it.
• Each new node installs Qdrant, then bootstraps into the cluster through the first peer over the private/overlay network (consensus and node-to-node traffic ride port 6335, which is opened between the service's own nodes only).
• All nodes serve the full API on 6333/6334 with the same API key — requests to any node are routed to the right shard internally.

Spreading data across nodes

Where your data lives is decided per collection, when you create it. A collection created with defaults keeps all its data on one node. To replicate and shard:

curl -X PUT -H "api-key: $QDRANT_API_KEY" -H "Content-Type: application/json" \
  -d '{"vectors": {"size": 1536, "distance": "Cosine"}, "replication_factor": 2, "shard_number": 6}' \
  http://<any-node>:6333/collections/documents

• replication_factor: 2 keeps two copies of every shard, so the collection survives a node going down.
• shard_number splits the collection so it can outgrow a single machine. Pick roughly nodes × 2 at creation time — it can't be changed cheaply later.

Checking the cluster

managed service vectors check-cluster

Shows how many peers the cluster has versus how many it should have, this node's consensus role, and any pending operations. The dashboard also charts a Cluster peers gauge and every node's health.

Cluster limitations

• Backups are single-node only. In cluster mode the daily backup skips (one node's files are not a complete backup) and restore refuses to run. Use replication_factor: 2+ for redundancy.
• Removing nodes is manual. Scaling replicas down removes the servers, but the cluster remembers the departed peers; check-cluster will show them missing. Move or re-replicate their shards first, then remove the peers via Qdrant's cluster API.
• A cluster needs the private/overlay network — nodes must be able to reach each other. managed apply sets this up automatically when the servers support it.

Backups

On a single node, a full backup runs every 24 hours: Qdrant is paused for a moment while its data directory is streamed to object storage as a compressed archive — a byte-exact, consistent copy — then started again. Retention follows the daily/weekly/monthly scheme (see the parameters above).

managed service vectors backup            # take a backup now (brief pause)
managed service vectors backup-list       # list what's in storage
managed service vectors restore --arg confirm=yes

Restore replaces everything in Qdrant with the backup contents — it previews what it will do and requires the confirm=yes argument. If the download fails mid-restore, the original data is put back untouched.

Commands

Command	Description
managed service <name> status	Server status and collection list
managed service <name> check-cluster	Cluster membership and consensus health
managed service <name> backup	Back up now (single-node only; brief pause)
managed service <name> backup-list	List available backups in storage
managed service <name> restore	Restore from the latest (or specified) backup

Ports

Port	Protocol	Open to	Purpose
6333	tcp	private networks	HTTP API (REST + JSON)
6334	tcp	private networks	gRPC API
6335	tcp	this service's nodes only	Cluster consensus & node-to-node transfer

How it works

The service installs the official static Qdrant binary from GitHub releases — checksum-verified for the default version — and runs it under systemd as the unprivileged qdrant user. The API key is handed to the process through a root-only environment file, never on a command line or in a world-readable config. Telemetry is disabled.

Distributed mode is always on: a lone node runs as a 1-peer cluster. That keeps every declared port really listening, and it means adding replicas later grows the cluster without touching the first node.

Where the data lives

Qdrant keeps everything in /var/lib/qdrant on the server (storage/ for collections, snapshots/ for snapshots). managed installs onto whatever disk layout the server already has — on OVH bare metal, set up Storage & RAID before the first apply.