Qdrant Vector Database for Local Development

This project provides a ready-to-use local development environment for the Qdrant vector database using Docker Compose.

Prerequisites

Before you begin, ensure you have the following installed on your system:

• Docker Desktop (which includes Docker and Docker Compose).

Getting Started

Follow these steps to start the Qdrant service on your local machine.

0. Clone this repo locally

In a directory you want to place this project, run: git clone https://github.com/ubc/tlef-qdrant

1. Start the Service

Navigate to the root of this project directory in your terminal and run the following command to start the Qdrant container in detached mode (it will run in the background):

docker-compose up -d

2. Verify the Service is Running

You can check the status of the running container with:

docker-compose ps

You should see a service named qdrant-local-dev with a status of Up.

3. Access the Qdrant Web UI

Once the service is running, you can access the Qdrant Web UI in your browser at:

http://localhost:6333/dashboard

This dashboard allows you to view collections, search points, and interact with your vector database.

Service Configuration

API Endpoints

The Qdrant service exposes two main ports on your local machine:

• Port 6333 (HTTP): The REST API endpoint for all database operations. You will use this for making HTTP requests to create collections, add points, search, etc. The Web UI dashboard also runs on this port at /dashboard.
• Port 6334 (gRPC): A high-performance binary protocol used by the official Qdrant client libraries (e.g., for Python, TypeScript/JavaScript).

API Key Authentication

This service uses Qdrant's JWT RBAC feature to support multiple application-specific API keys with different permission scopes.

Keys

Key	How stored	Access
Master key	api_key in docker-compose.yml config	Full admin — all collections + management
App key: my-app-1	Comment in docker-compose.yml	All collections, read + write
App key: my-app-2	Comment in docker-compose.yml	my-app-2 collection only, read + write

All keys are passed identically in the api-key header. The app keys are JWT tokens signed with the master key.

Generating local dev app JWT tokens

After changing the master key, regenerate the local dev app tokens:

export QDRANT_MASTER_KEY="super-secret-dev-key"
./scripts/generate-dev-keys.sh

Paste the output tokens into the comment block in docker-compose.yml, then restart the container.

Generating a production app key

To create a real, scoped app key for a named application (for use in Vault/Ansible):

./scripts/new-app-key.sh

The script will prompt for the app name, master key (hidden input), and one or more collections with their access levels (r read-only or rw read-write). It confirms your input before generating, and copies the token to your clipboard if pbcopy is available.

Example curl requests

# Using the master key
curl http://localhost:6333/collections \
  --header 'api-key: super-secret-dev-key'

# Using an app key (JWT token)
curl http://localhost:6333/collections \
  --header 'api-key: <paste token here>'

# No key — returns 401 Unauthorized
curl http://localhost:6333/collections

Running the test suite

The test suite verifies that all keys work as expected and that collection-scoped restrictions are enforced:

export QDRANT_MASTER_KEY="super-secret-dev-key"
export QDRANT_APP_KEY_MY_APP_1="<app-1 token from generate-dev-keys.sh>"
export QDRANT_APP_KEY_MY_APP_2="<app-2 token from generate-dev-keys.sh>"
./scripts/test-keys.sh

The script creates two temporary test collections (my-app-1 and my-app-2), runs 17 scenarios, then deletes them. Your existing collections are not affected.

Web UI

The Qdrant dashboard (port 6333) lets you see collections and results after running the tests:

http://localhost:6333/dashboard

Data Persistence

All data created in your Qdrant instance (collections, vectors, etc.) is stored in the ./qdrant_data directory within this project.

This means your data will persist even if you stop and restart the container. If you want to start with a fresh, empty database, you can stop the service and delete this directory.

Managing the Service

Stopping the service and viewing logs:

Stop the Service

To stop the Qdrant container without deleting your data, run:

docker-compose down

View Logs

To view the real-time logs from the Qdrant service for debugging, run:

docker-compose logs -f

Press Ctrl+C to stop viewing the logs.