> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hellocobi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Qdrant Setup

> Configure the Qdrant vector database for semantic search and document embeddings

## Overview

Qdrant is the vector database used by Cobi to store and search document embeddings. The `qdrant` dependency chart deploys it as a StatefulSet with persistent storage.

**Default ports:**

* `6333` — HTTP REST API (used by the backend)
* `6334` — gRPC API

The backend connects to Qdrant at `http://<release-name>-qdrant:6333` via the `QDRANT_URL` environment variable.

## Configuration in values.yaml

```yaml theme={null}
qdrant:
  enabled: true

  image:
    repository: qdrant/qdrant
    tag: "v1.16.2"          # pin to a specific version — "latest" can break on upgrades
    pullPolicy: IfNotPresent

  service:
    httpPort: 6333
    grpcPort: 6334

  persistence:
    enabled: true
    storageClass: ""        # use cluster default; set to "local-path" or "nfs-csi" for on-prem
    accessModes:
      - ReadWriteOnce
    size: 10Gi              # increase for large document collections
```

## Sizing the PVC

Qdrant stores vectors on disk. The required space depends on:

| Factor              | Impact                                           |
| ------------------- | ------------------------------------------------ |
| Number of documents | Each document generates one or more vectors      |
| Embedding dimension | Typical embedding models use 384–1536 dimensions |
| Index type          | HNSW graph adds \~1.5× overhead over raw vectors |

A rough estimate: **\~1 Gi per 500 000 vectors** at 768 dimensions with HNSW indexing. Start with `10Gi` and expand the PVC when utilization reaches 70%.

## On-Premises StorageClass

For clusters without a cloud storage provisioner, set a local or NFS-backed StorageClass:

```yaml theme={null}
qdrant:
  persistence:
    storageClass: "local-path"   # rancher local-path-provisioner
    size: 20Gi
```

## Exposing Qdrant (optional)

Qdrant is a ClusterIP service by default (internal only). To expose it for external tooling (e.g., Qdrant Web UI or admin scripts), add an Ingress:

```yaml theme={null}
qdrant:
  ingress:
    enabled: true
    ingressClassName: nginx
    annotations: {}
    hosts:
      - host: qdrant.example.com
        paths:
          - path: /
            pathType: Prefix
            servicePort: 6333
    tls: []
```

<Warning>
  Do not expose Qdrant publicly without authentication. The Qdrant HTTP API has no built-in auth by default — restrict access to internal networks or use an ingress that enforces authentication.
</Warning>

## Verify Qdrant

```bash theme={null}
# Port-forward the Qdrant HTTP API
kubectl port-forward -n cobi svc/cobi-dashboard-qdrant 6333:6333

# Check cluster health
curl http://localhost:6333/healthz

# List collections
curl http://localhost:6333/collections
```

A healthy response from `/healthz` returns `{"title":"qdrant - vector search engine","version":"..."}`.

## Connecting the Backend

Set the following variables in the backend Secret. The service name follows the pattern `<release-name>-qdrant` — if your release is named `cobi-dashboard`, the service is `cobi-dashboard-qdrant`.

### In-cluster Qdrant (deployed via this chart)

```bash theme={null}
kubectl create secret generic cobi-backend-secrets \
  --namespace cobi \
  --from-literal=QDRANT_URL="http://cobi-dashboard-qdrant:6333" \
  --from-literal=QDRANT_LOCAL_ONLY="true" \
  --from-literal=QDRANT_API_KEY="" \
  --from-literal=QDRANT_CLUSTER_KEY="" \
  --from-literal=QDRANT_COLLECTION_PREFIX="prod_" \
  # ... other keys
```

### External / standalone on-prem Qdrant

If Qdrant is running on a separate server or another cluster:

```bash theme={null}
kubectl create secret generic cobi-backend-secrets \
  --namespace cobi \
  --from-literal=QDRANT_URL="http://qdrant.internal.example.com:6333" \
  --from-literal=QDRANT_LOCAL_ONLY="true" \
  --from-literal=QDRANT_API_KEY="" \
  --from-literal=QDRANT_CLUSTER_KEY="" \
  --from-literal=QDRANT_COLLECTION_PREFIX="prod_" \
  # ... other keys
```

Keep `QDRANT_LOCAL_ONLY="true"` for any self-hosted Qdrant regardless of where it runs. Set it to `"false"` only when using [Qdrant Cloud](https://cloud.qdrant.io).

### Qdrant Cloud

```bash theme={null}
kubectl create secret generic cobi-backend-secrets \
  --namespace cobi \
  --from-literal=QDRANT_URL="https://<cluster-id>.us-east4-0.gcp.cloud.qdrant.io:6333" \
  --from-literal=QDRANT_LOCAL_ONLY="false" \
  --from-literal=QDRANT_API_KEY="<qdrant-cloud-api-key>" \
  --from-literal=QDRANT_CLUSTER_KEY="<qdrant-cluster-key>" \
  --from-literal=QDRANT_COLLECTION_PREFIX="prod_" \
  # ... other keys
```

### Backend environment variable reference

| Variable                   | Required   | Description                                                                                                                                 |
| -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `QDRANT_URL`               | Yes        | Full HTTP(S) URL of the Qdrant REST API, including port                                                                                     |
| `QDRANT_LOCAL_ONLY`        | Yes        | `"true"` for self-hosted (in-cluster or on-prem); `"false"` for Qdrant Cloud                                                                |
| `QDRANT_API_KEY`           | Cloud only | API key from the Qdrant Cloud console. Leave empty for local                                                                                |
| `QDRANT_CLUSTER_KEY`       | Cloud only | Cluster key from the Qdrant Cloud console. Leave empty for local                                                                            |
| `QDRANT_COLLECTION_PREFIX` | No         | Prefix prepended to all collection names. Use to namespace multiple environments (e.g. `"prod_"`, `"staging_"`) sharing one Qdrant instance |

## Backup

Qdrant supports snapshot-based backups via its REST API:

```bash theme={null}
# Create a snapshot of a collection
curl -X POST http://localhost:6333/collections/<collection-name>/snapshots

# List snapshots
curl http://localhost:6333/collections/<collection-name>/snapshots
```

Snapshots are written to the Qdrant PVC. Copy them to external storage using a CronJob or `kubectl cp`.