---
title: "Deploy Qdrant"
description: "Vector database for storing embeddings and searching by similarity"
category: "Storage"
url: https://railway.com/deploy/qdrant-cluster
---

# Deploy Qdrant

Vector database for storing embeddings and searching by similarity

**[Deploy Qdrant on Railway](https://railway.com/template/qdrant-cluster)**

- **Creator:** A3A
- **Category:** Storage
- **Total deploys:** 1

## Template content

### qdrant-3 https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/qdrant.svg

- **Image:** qdrant/qdrant:v1.19.0
- **Health check:** /livez

### qdrant-1 https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/qdrant.svg

- **Image:** qdrant/qdrant:v1.19.0
- **Health check:** /livez

### gateway https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/caddy.svg

- **Source:** https://github.com/gridalpha/qdrant-gateway-railway
- **Health check:** /gatewayz
- **Public domain:** Yes

### qdrant-2 https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/qdrant.svg

- **Image:** qdrant/qdrant:v1.19.0
- **Health check:** /livez

## Buckets

- **snapshots**

## Documentation

# Deploy and Host Qdrant on Railway

Qdrant is an open-source vector database written in Rust that stores embeddings alongside arbitrary JSON payloads and answers nearest-neighbour queries in milliseconds. It is the retrieval layer behind retrieval-augmented generation, semantic search, recommendations and deduplication — anywhere an app needs "find the things most similar to this" rather than "the rows matching this WHERE clause". Its distinguishing feature is filtered vector search: payload conditions are applied *during* graph traversal, so "the ten closest documents for this tenant, tagged `policy`" stays fast instead of degrading into a post-filter scan.

Self-host Qdrant on Railway and this template gives you the shape Qdrant documents for production, not a single container. Three nodes join one Raft cluster over the private network, each with its own volume. A Caddy gateway holds the only public domain and round-robins the REST API across all three, so losing a node does not take the endpoint down. New collections default to six shards at replication factor two, and a managed object storage bucket holds snapshots, so a backup taken on one node restores from any of them.

![Diagram of three Qdrant nodes behind a Caddy gateway on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1787332173/qdrant-architecture.png)

## Getting Started with Qdrant on Railway

Deploying generates one public URL on the gateway. There are no default credentials to change: an API key is generated at deploy time and every data route rejects requests without it. Copy it from `QDRANT__SERVICE__API_KEY` on `qdrant-1`, then open `/dashboard` on your new domain, which prompts for the key on first load.

Confirm the cluster is healthy first: open the **Console** and run `GET cluster`, which should show three `peers`, one node with `"role": "Leader"`, and an empty `message_send_failures`. Create your first collection from the **Collections** tab, matching the vector size to your embedding model (1536 for OpenAI `text-embedding-3-small`, 768 for most sentence-transformers). Upsert a few points, query them from the Console, then open the collection's **Cluster** tab to watch its shards spread across the peers. From your app, point any Qdrant client at the same URL with the key as the `api-key` header.

![Qdrant dashboard listing the handbook collection across six shards](https://res.cloudinary.com/rroe4rtk/image/upload/v1787332176/qdrant-collections.png)
![Qdrant cluster view showing shard replicas spread over three peers](https://res.cloudinary.com/rroe4rtk/image/upload/v1787332178/qdrant-cluster-shards.png)
![Qdrant points browser showing stored payloads and vector previews](https://res.cloudinary.com/rroe4rtk/image/upload/v1787332183/qdrant-points.png)

## About Hosting Qdrant

Qdrant is a purpose-built vector search engine, not an extension bolted onto a general-purpose database. Teams self-host it when embeddings become core to the product and a managed service is too expensive, too slow, or ruled out by data residency. Being a single static Rust binary with no JVM and no external coordinator, it is unusually cheap to run at a given scale.

Key features:

- **Filtered HNSW search** — payload conditions applied during traversal, not after
- **Hybrid and sparse vectors** — dense, sparse and multi-vector search with server-side fusion
- **Quantization** — scalar, binary and 4-bit modes that cut memory dramatically
- **JWT access control** — scoped read-only or collection-limited tokens

The three `qdrant-N` services are peers, not primaries and replicas: any accepts any request and forwards it to whichever peer holds the shard, which is why a round-robin load balancer is safe in front of them. Raft consensus on private port 6335 keeps topology and collection definitions consistent. The `gateway` health-checks each node and routes around unhealthy ones, holding no credential of its own. The bucket exists because a Railway volume attaches to one service — object storage is what makes a snapshot visible cluster-wide.

## Why Deploy Qdrant on Railway

Railway removes the work that makes a self-hosted vector cluster unattractive:

- Three nodes, three volumes and a load balancer provisioned in one click
- Private networking between peers, with no ports exposed to the internet
- Managed S3-compatible object storage wired up for snapshots
- Usage-based pricing with no per-vector or per-query fees

## Common Use Cases

- **Retrieval-augmented generation** — ground an LLM in your documents, filtered per tenant so one customer never retrieves another's data
- **Semantic and hybrid search** — meaning-based ranking combining dense and sparse vectors in one query
- **Recommendations and deduplication** — "more like this" feeds, near-duplicate detection, image and audio matching
- **Long-term agent memory** — a durable store AI agents write to and search across sessions

## Dependencies for Qdrant

- `qdrant/qdrant:v1.19.0` — three nodes, each with a 6333 REST API, a 6334 gRPC API and a 6335 Raft peer port
- `gridalpha/qdrant-gateway-railway` — Caddy 2 load balancer, from this [source repository](https://github.com/gridalpha/qdrant-gateway-railway)
- One object storage bucket for snapshots, and three volumes mounted at `/qdrant/storage`

### Environment Variables Reference

| Variable | Purpose |
|---|---|
| `QDRANT__SERVICE__API_KEY` | Full-access key sent as the `api-key` header |
| `QDRANT__SERVICE__READ_ONLY_API_KEY` | Key permitting reads and search but no writes |
| `QDRANT__SERVICE__HOST` | Listen address; must stay `::` for peers to reach each other |
| `QDRANT__STORAGE__COLLECTION__REPLICATION_FACTOR` | Copies of each shard for new collections |
| `QDRANT__STORAGE__SNAPSHOTS_CONFIG__SNAPSHOTS_STORAGE` | `s3` for the bucket, `local` for the volume |

### Deployment Dependencies

- [Qdrant on GitHub](https://github.com/qdrant/qdrant), the [documentation](https://qdrant.tech/documentation/) and the [distributed deployment guide](https://qdrant.tech/documentation/scaling/distributed_deployment/)
- [`qdrant/qdrant` on Docker Hub](https://hub.docker.com/r/qdrant/qdrant)
- Official clients for Python, JavaScript, Rust, Go, Java and .NET

## Hardware Requirements for Self-Hosting Qdrant

Memory is what matters. A rough HNSW estimate is `vectors × dimensions × 4 bytes × 1.5`, so a million 768-dimension vectors needs about 4.5 GB before quantization — binary quantization cuts that by up to 32×.

| Resource | Minimum per node | Recommended per node |
|---|---|---|
| CPU | 1 vCPU | 4+ vCPU |
| RAM | 1 GB | 4–8 GB, sized to your index |
| Storage | 5 GB volume | 20 GB+, roughly 2× raw vector size |
| Runtime | Linux container, x86-64 or ARM64 | Same |

## Self-Hosting Qdrant

A single node runs from one container. The following is a `docker run` with an API key and a persistent volume:

```
docker run -p 6333:6333 -p 6334:6334 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY="your-secret-key" \
  qdrant/qdrant:v1.19.0
```

Clustering needs no custom image or start command — it is configured entirely through environment variables. The first peer advertises itself with `QDRANT_URI`; later peers also set `QDRANT_BOOTSTRAP`. The following is the environment for a second node joining a cluster:

```
QDRANT__CLUSTER__ENABLED=true
QDRANT__CLUSTER__P2P__PORT=6335
QDRANT__SERVICE__HOST=::
QDRANT_URI=http://qdrant-2.railway.internal:6335
QDRANT_BOOTSTRAP=http://qdrant-1.railway.internal:6335
```

Two details decide whether a self-hosted cluster works. `QDRANT__SERVICE__HOST` also controls the Raft peer listener, so the default `0.0.0.0` leaves peers unreachable on IPv6-only private networks. And with no startup ordering, a node whose bootstrap target is not up yet exits — give joining nodes an always-restart policy so they retry until the cluster forms.

## How Much Does Qdrant Cost to Self-Host?

Qdrant is free and open source under Apache 2.0, with no feature gating, node limit or seat count in the self-hosted build. Clustering, replication, quantization and JWT access control are all in the open-source binary. Qdrant Cloud is the paid managed offering; self-hosting costs only infrastructure, so on Railway you pay for what the four services consume.

## FAQ

**What is Qdrant?**
An open-source vector database and similarity search engine. It stores high-dimensional embeddings with JSON payloads and returns the nearest matches to a query vector, optionally constrained by filters on those payloads.

**What does this Railway template deploy?**
Three Qdrant nodes forming one Raft cluster, each on its own volume, a Caddy gateway holding the public domain and load-balancing across them, and a bucket for snapshots. New collections default to six shards at replication factor two.

**Why does the template include a gateway instead of exposing Qdrant directly?**
A Railway domain points at one service, so exposing a node directly makes it a single point of failure. The gateway health-checks all three and routes around a failed one, and keeps the Raft peer port private — which Qdrant's docs require, since that port can perform writes.

**How do I enable API key authentication in self-hosted Qdrant?**
Set `QDRANT__SERVICE__API_KEY` and send it as the `api-key` header; this template does it for you. Note that `/`, `/healthz`, `/livez`, `/readyz` and the `/dashboard` static files stay anonymous by design — the dashboard behaves like a login screen, and every data call it makes still needs the key.

**Which Qdrant version does this template run, and how do I upgrade it?**
It pins `v1.19.0`. Qdrant migrates its on-disk format between consecutive minors only, so upgrade one minor at a time and snapshot first.


## Similar templates

- [Garage S3 Storage](https://railway.com/deploy/garage-s3-storage) — Ultra-light S3 server: fast, open-source, plug-and-play.
- [Redis](https://railway.com/deploy/redis-1) — Self Host Latest Redis with Railway
- [EasyImg](https://railway.com/deploy/easyimg) — Simple self-hostable Nuxt.js personal image hosting system.

Open this page in a browser: https://railway.com/deploy/qdrant-cluster