Qdrant stores vectors and associated metadata for similarity search. It is infrastructure for an AI knowledge system, not a language model or a chatbot by itself. A separate embedding model turns text into vectors, and your application retrieves relevant fragments before asking a language model to answer.
Target: Ubuntu Server 24.04 LTS, x86-64, SSH and a sudo account. Documentation reviewed 15 November 2026. Commands have not been tested end to end on Ubuntu.
Before you start
For a small evaluation, start with about 2 vCPUs, 4 GB RAM and 15 GB free disk. Storage and memory depend on vector count, dimensions, payloads, indexes and replicas. Embedding and generation capacity are separate. Use fictional data for the first test and keep sensitive metadata out until access/retention rules are defined.
Resource figures are planning estimates for a small evaluation, not performance guarantees or plan specifications. A VPS/VDS does not imply a GPU. Check available memory, storage and resources before ordering.
On a fresh Ubuntu installation, use the packages below. If Docker is already installed from another repository, keep that installation and check compatibility first: do not mix Docker CE and docker.io packages. Use Compose v2; if the package is missing, check that Ubuntu Universe is enabled.
sudo apt update
sudo apt install -y docker.io docker-compose-v2 curl openssl
sudo systemctl enable --now docker
sudo docker compose version
All examples publish ports only on the server’s 127.0.0.1. Access them from your computer through an SSH tunnel; a domain is unnecessary. Do not open these ports to the Internet. An internal container listener on 0.0.0.0 does not change the host’s loopback-only published port.
Each project below is a new installation. Do not rerun secret-generation steps against an existing deployment.
1. Create an authenticated private database
Save the key in .env and the YAML as compose.yaml. Only REST is published on loopback; gRPC and cluster ports are not exposed. The data and snapshot stores are persistent.
umask 077
mkdir -p ~/ai-qdrant
cd ~/ai-qdrant
printf 'QDRANT_KEY=%s\n' "$(openssl rand -hex 32)" > .env
services:
qdrant:
image: qdrant/qdrant:latest
restart: unless-stopped
ports:
- "127.0.0.1:6333:6333"
environment:
QDRANT__SERVICE__API_KEY: ${QDRANT_KEY:?set QDRANT_KEY in .env}
volumes:
- data:/qdrant/storage
- snapshots:/qdrant/snapshots
volumes:
data:
snapshots:
2. Test authorization and create a toy collection
Run on the VPS. The unauthenticated collections request should be rejected (401/403). The four-dimensional vectors below are synthetic numeric examples, not real text embeddings. Create this collection only on a new test instance; do not replace an existing production collection.
sudo docker compose up -d
curl -s -o /dev/null -w '%{http_code}
' http://127.0.0.1:6333/collections
set -a
. ./.env
set +a
curl --fail-with-body -X PUT http://127.0.0.1:6333/collections/guide_demo -H "api-key: $QDRANT_KEY" -H 'Content-Type: application/json' -d '{"vectors":{"size":4,"distance":"Cosine"}}'
curl --fail-with-body -X PUT 'http://127.0.0.1:6333/collections/guide_demo/points?wait=true' -H "api-key: $QDRANT_KEY" -H 'Content-Type: application/json' -d '{"points":[{"id":1,"vector":[1,0,0,0],"payload":{"text":"Example: backups are stored off-server."}},{"id":2,"vector":[0,1,0,0],"payload":{"text":"Example: SSH uses keys."}}]}'
curl --fail-with-body -X POST http://127.0.0.1:6333/collections/guide_demo/points/query -H "api-key: $QDRANT_KEY" -H 'Content-Type: application/json' -d '{"query":[1,0,0,0],"limit":1,"with_payload":true}'
unset QDRANT_KEY
3. Turn the example into a document-search design
The nearest result should be point 1. For real documents, split text into chunks, embed with one chosen model and use its actual vector dimension; query with that same model. Changing the embedding model normally requires re-embedding and a matching collection. Enforce document permissions in your application before retrieving/returning passages; a shared API key is not per-customer isolation. Treat document instructions as untrusted text.
4. Access and back up the vector store
Use the tunnel from your computer for a REST client or local application. Copy both persistent stores consistently with the container stopped for this single-node example; preserve .env separately. Keep original documents and the embedding model/version too: vectors alone are not a complete recoverable knowledge base. A larger deployment needs tested snapshot/restore and capacity planning, rather than a live filesystem copy.
ssh -N -L 127.0.0.1:6333:127.0.0.1:6333 YOUR_USER@YOUR_SERVER_IP
Updates and recovery
Before upgrading, stop the application for a consistent backup, keep data and secrets off the VPS, and test recovery on a separate instance. Moving image tags in these examples are for initial evaluation; pin a reviewed release tag or digest before ongoing use. Record the current digest with sudo docker image inspect IMAGE_NAME --format '{{json .RepoDigests}}'. Avoid unattended upgrades without compatibility checks, and do not delete persistent volumes with down -v.
If startup fails, inspect sudo docker compose ps, recent logs, free disk and memory. Do not share logs containing keys, prompts or personal data. For directory-permission errors, check the expected UID/GID and ownership instead of granting 777. Set up HTTPS, authentication and request limits before sharing access.