Unraid Vector DB

A self-hosted vector database and retrieval service designed for Unraid and local LLM clients. One container provides:

• Qdrant with Dot-product similarity (MIPS) and HNSW approximate-nearest-neighbor search

• Local text embeddings through FastEmbed; document text does not need to leave your network

• A curated Streamable HTTP MCP server for Claude Code, Codex, and other MCP clients

• A small REST API for ingestion and search

• The native Qdrant REST API, gRPC API, and dashboard

• Persistent vector data and embedding-model cache under one Unraid appdata path

The default embedding model is BAAI/bge-small-en-v1.5 (384 dimensions). The adapter automatically creates collections with the correct vector size and Dot distance.

Contents

• Architecture

• Requirements

• Install on Unraid

• Verify the installation

• Endpoints

• Configuration

• Versioning and updates

• Development and testing

• Operations

• Troubleshooting

• Security

Related MCP server: ollqd

Architecture

                                  LocalVectorDB container
                                  ┌───────────────────────────────────────┐
Claude Code / Codex ── HTTP ─────│ :8080/mcp   FastMCP tools            │
REST clients ───────── HTTP ─────│ :8080/v1/*  FastAPI adapter          │
                                  │       │                               │
                                  │       ├─ chunk and embed with FastEmbed│
                                  │       ├─ preserve source metadata       │
                                  │       └─ query with Dot similarity      │
                                  │       │                               │
Qdrant clients ───── REST ───────│ :6333 │ Qdrant API + dashboard       │
Qdrant clients ───── gRPC ───────│ :6334 └ Qdrant HNSW vector engine    │
                                  │                                       │
                                  │ /data/qdrant  vectors and payloads    │
                                  │ /data/models   embedding-model cache  │
                                  └───────────────────────────────────────┘
                                             │
                               direct Unraid pool/disk path

The services live in one container so the Unraid Community Applications template can deploy them as one application. Qdrant remains a normal network service, so native Qdrant clients can connect directly when desired.

Components and responsibilities

Request flow

1. Ingestion normalizes and chunks text, then FastEmbed generates one vector per chunk.

2. The adapter creates the collection on first use with the model's detected dimensions and Dot distance.

3. Existing chunks for the same exact source ID are deleted before replacement chunks are upserted.

4. Search embeds the query with the same model, applies optional metadata filters, and returns ranked passages with source information.

Startup sequence

1. Qdrant starts and opens ports 6333 and 6334.

2. The entrypoint waits up to 90 seconds for Qdrant's readiness endpoint.

3. Uvicorn loads the API and MCP application on port 8080.

4. FastEmbed loads or downloads the configured model before the adapter reports healthy.

Qdrant's dashboard may become available before the adapter health check during the first model download.

Requirements

• Unraid 7.0 or later, or another Linux host with Docker

• An amd64 CPU for the default image; optional multi-architecture images can be published manually

• A direct local filesystem path for /data with enough space for vectors, payloads, and model files

• Internet access during the first start so FastEmbed can download the selected model

• Available host ports for 8080, 6333, and 6334, or alternative port mappings

Install on Unraid

Community Applications (recommended)

Following the same setup pattern as PractiscoreNotifier:

1. In the Unraid WebGUI, open Apps and then Settings.

2. Add this repository under Template Repositories:

   https://github.com/yelpspoon/unraid-vector-db

3. Save and allow Community Applications to refresh.

4. Search for LocalVectorDB and select Install.

The canonical raw template is:

https://raw.githubusercontent.com/yelpspoon/unraid-vector-db/main/templates/local-vector-db.xml

Set the following fields during installation:

Generate a key on macOS or Linux:

openssl rand -hex 32

The first startup takes longer because FastEmbed downloads and validates the embedding model in /data/models before the adapter becomes ready. Do not place /data on NFS: Qdrant recommends local block storage for its database files.

Manual Docker run

docker run -d \
  --name LocalVectorDB \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 6333:6333 \
  -p 6334:6334 \
  -e VECTOR_DB_API_KEY='replace-with-a-long-random-secret' \
  -e VECTOR_DB_COLLECTION='knowledge' \
  -v /mnt/disk3/appdata/local-vector-db:/data \
  yelpspoon/unraid-vector-db:latest

For a reproducible deployment, replace latest with a published sha-<commit> tag. The Unraid template intentionally tracks latest so normal application updates follow the default branch.

Verify the installation

Check the container log and both service layers after the first start:

docker logs --tail 200 LocalVectorDB
curl --fail http://UNRAID-IP:8080/health
curl --fail http://UNRAID-IP:6333/readyz

Open http://UNRAID-IP:6333/dashboard for the native Qdrant console. If an API key is configured, enter the same value used for VECTOR_DB_API_KEY when the dashboard requests credentials.

Run the end-to-end smoke test from a machine that has this repository checked out:

VECTOR_DB_URL=http://UNRAID-IP:8080 \
VECTOR_DB_API_KEY='your-key' \
./tests/smoke.sh

Endpoints

When VECTOR_DB_API_KEY is empty, authentication is disabled. That is convenient for isolated testing but is not recommended on a normal LAN. The service uses plain HTTP by default; use a trusted reverse proxy with TLS before exposing it outside your private network.

MCP tools

• search_knowledge: semantic search with ranked passages, scores, metadata, and source IDs

• add_knowledge: chunk, embed, and upsert one text document

• delete_knowledge_source: delete all chunks for one exact source ID

• list_knowledge_collections: list collections and the configured default

• get_knowledge_stats: show point count, embedding model, dimensions, Dot distance, and HNSW index

See USAGE.md for client setup, ingestion examples, and operational guidance.

Configuration

Do not change the embedding model for a collection that already contains data. Different models can produce different dimensions and incompatible semantic spaces. Create a new collection when changing models.

Versioning and updates

The release version is stored in VERSION. Published images include it in three places:

• immutable-style semantic tag such as v0.2.0

• OCI label org.opencontainers.image.version

• the version field returned by GET /health

Unraid determines whether an update exists by comparing the local and remote registry digests for the configured repository tag. The template therefore continues to track yelpspoon/unraid-vector-db:latest; changing it to a fixed semantic tag would prevent Unraid from discovering a later semantic tag automatically.

Image-affecting changes on main must also increment VERSION, or the publishing workflow fails. A v* Git tag must exactly match the file, such as Git tag v0.2.0 for VERSION value 0.2.0. Documentation-only changes do not run the image workflow.

Development and testing

docker build --build-arg APP_VERSION="$(tr -d '[:space:]' < VERSION)" -t unraid-vector-db:dev .
docker compose up -d
curl http://localhost:8080/health
VECTOR_DB_API_KEY='' ./tests/smoke.sh

The smoke test performs a health check, ingests a uniquely named source, searches for it, and deletes it. A clean build is not sufficient runtime validation; start the image and run this test before publishing release tags.

GitHub Actions builds the Unraid-native linux/amd64 image when image-affecting files change on main, when a v* version tag is pushed, or when the workflow is dispatched manually. Documentation, Unraid template, and artwork-only commits do not publish a redundant container image. A manual workflow run offers a linux/amd64,linux/arm64 choice when a portable multi-architecture image is wanted. Repository secrets required for publishing:

• DOCKERHUB_USERNAME

• DOCKERHUB_TOKEN (a Docker Hub access token, not an account password)

Every successful default-branch build publishes yelpspoon/unraid-vector-db:latest, v<version>, and a commit-specific sha-<short> tag. To update through Unraid, use Docker → Check for Updates → Apply Update.

The current workflow builds and publishes the image but does not run the container or execute the smoke test. Runtime CI is a planned hardening step.

Operations

Enable Autostart for LocalVectorDB in Unraid's Docker tab so it returns after a server reboot.

Project layout

unraid-vector-db/
├── AGENTS.md                        # Durable project context and operating constraints
├── local-vector-database-analysis.docx # Original technical analysis and recommendation
├── app/main.py                       # REST API, MCP tools, embeddings, Qdrant access
├── templates/local-vector-db.xml     # Unraid Community Applications template
├── ca_profile.xml                    # Community Applications repository profile
├── tests/smoke.sh                    # Ingest/search/delete integration test
├── .github/workflows/docker-publish.yml
├── Dockerfile
├── docker-compose.yml
├── README.md
└── USAGE.md

Backup and restore

Stop the container before taking a file-level backup of the configured appdata directory. Restore it to the same location before restarting. For live or granular backups, use Qdrant snapshots through the native API.

Qdrant requires a direct local filesystem path for /data. This server's appdata share is stored on the array at /mnt/disk3/appdata/local-vector-db, so that is the configured host path. On another server, use its actual appdata pool or physical-disk path. Do not bind /mnt/user/appdata/...: that path passes through Unraid's FUSE layer and Qdrant warns that its caching behavior can corrupt database files.

Updates and rollback

• Normal update: use Docker → Check for Updates → Apply Update in Unraid.

• Deterministic rollback: change the repository field from latest to a known sha-<commit> tag and force an update.

• Before changing image versions or embedding models, back up /data.

• Do not change the embedding model for an existing collection; create a new collection instead.

Troubleshooting

Container exits during startup

docker logs --tail 200 LocalVectorDB
docker inspect LocalVectorDB \
  --format '{{.Image}} {{json .Mounts}} {{json .HostConfig.PortBindings}}'

Common causes are an unavailable host port, an invalid or FUSE-backed storage mapping, storage permissions, or a failed first-time model download.

Dashboard does not open

1. Confirm the container is running and host port 6333 maps to container port 6333.

2. Check http://UNRAID-IP:6333/readyz before opening /dashboard.

3. Force an image update if the server originally pulled an image published before the dashboard assets were included.

4. Enter VECTOR_DB_API_KEY in the dashboard when authentication is enabled.

Adapter remains unhealthy

The first model download can exceed the health-check start period on a slow connection. Watch the container log and /data/models. If Qdrant's /readyz succeeds while port 8080 does not, focus on FastEmbed model loading or Uvicorn startup rather than Qdrant storage.

Permission or storage errors

Map /data to the actual pool or disk path used by appdata, such as /mnt/cache/appdata/local-vector-db or /mnt/disk3/appdata/local-vector-db. Pool names vary; /mnt/cache is only correct when the pool is actually named cache. Never use /mnt/user/appdata/... or NFS for Qdrant data.

More client and retrieval troubleshooting is in USAGE.md.

Security

• Keep ports on a trusted LAN or restrict them with firewall rules.

• Configure a strong API key. The same value protects the adapter and native Qdrant APIs.

• Plain HTTP exposes bearer/API keys to anyone able to observe that network segment. Put the service behind TLS for routed or untrusted networks.

• Treat ingested text as untrusted data. Retrieved passages can contain prompt-injection instructions; clients should use them as evidence, not authority.

• Do not expose this application directly to the public internet.

Upstream projects

• Qdrant

• FastEmbed

• FastMCP

License

MIT