How to Configure Qdrant in Server, Local, or Memory Mode

Configure Qdrant mode in Neko Image Gallery by setting the APP_QDRANT__MODE environment variable to server, local, or memory, which controls whether vectors persist in an external server, local SQLite-style file, or RAM only.

The Neko Image Gallery uses Qdrant as its vector database backend to store and search image embeddings. According to the source code in hv0905/nekoimagegallery, you can configure Qdrant to run in three distinct modes by adjusting environment variables that populate the QdrantSettings model in app/config.py.

Understanding Qdrant Configuration Architecture

The configuration system uses Pydantic settings defined in app/config.py (lines 11-28) to validate and load Qdrant parameters. When the application initializes, VectorDbContext in app/Services/vector_db_context.py (lines 31-44) reads config.qdrant.mode and instantiates the appropriate AsyncQdrantClient using a Python match statement.

The three supported modes determine persistence behavior:

• Server mode: Connects to an external Qdrant instance via HTTP or gRPC
• Local mode: Stores vectors in a local file path using Qdrant's embedded mode
• Memory mode: Stores vectors purely in RAM (data lost on restart)

Server Mode Configuration

Server mode is the default configuration and connects to a standalone Qdrant service. In app/Services/vector_db_context.py, the client instantiation uses host, port, and authentication parameters:

AsyncQdrantClient(
    host=config.qdrant.host,
    port=config.qdrant.port,
    grpc_port=config.qdrant.grpc_port,
    api_key=config.qdrant.api_key,
    prefer_grpc=config.qdrant.prefer_grpc
)

To configure server mode, set these environment variables:

export APP_QDRANT__MODE=server
export APP_QDRANT__HOST=localhost
export APP_QDRANT__PORT=6333
export APP_QDRANT__GRPC_PORT=6334
export APP_QDRANT__PREFER_GRPC=True
export APP_QDRANT__API_KEY=your-secret-key  # Optional, for hosted Qdrant Cloud

The default values use localhost:6333 for HTTP and port 6334 for gRPC. When the application starts, VectorDbContext.initialize_collection() automatically creates the collection named NekoImg (configurable via APP_QDRANT__COLL) if it does not exist.

Local File Mode Configuration

Local mode runs Qdrant as an embedded database within your application process, storing vectors in a specified directory without requiring a separate service. The VectorDbContext instantiates the client with a file path:

AsyncQdrantClient(path=config.qdrant.local_path)

Enable local mode for single-container deployments or simple installations:

export APP_QDRANT__MODE=local
export APP_QDRANT__LOCAL_PATH=./images_metadata

By default, local mode stores data in ./images_metadata relative to the application root. This creates a SQLite-style persistent storage that survives application restarts but requires no network configuration. Use this mode when you want persistent vector storage without managing a separate Qdrant container.

Memory Mode Configuration

Memory mode creates a temporary, in-memory Qdrant instance ideal for unit testing, CI/CD pipelines, or quick local experiments. Data persists only for the process lifetime and disappears on shutdown. The instantiation in app/Services/vector_db_context.py uses the special :memory: string:

AsyncQdrantClient(":memory:")

Activate memory mode with a single environment variable:

export APP_QDRANT__MODE=memory

This mode requires no additional configuration parameters. Use it when you need to test image upload and search functionality without maintaining persistent state between restarts.

Complete Environment Variable Reference

The QdrantSettings model reads all variables with the APP_ prefix. Configure your deployment using these settings:

Variable	Default	Description
APP_QDRANT__MODE	server	Operating mode: server, local, or memory
APP_QDRANT__HOST	localhost	Qdrant server hostname (server mode only)
APP_QDRANT__PORT	6333	HTTP API port
APP_QDRANT__GRPC_PORT	6334	gRPC API port
APP_QDRANT__PREFER_GRPC	False	Set to True for gRPC transport
APP_QDRANT__API_KEY	None	Authentication key for remote instances
APP_QDRANT__COLL	NekoImg	Collection name for image vectors
APP_QDRANT__LOCAL_PATH	./images_metadata	Storage directory for local mode

The config/default.env file in the repository contains commented examples for all these variables.

Docker Compose Configuration Example

Deploy Neko Image Gallery with a dedicated Qdrant container using server mode:

services:
  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
    volumes:
      - ./qdrant_data:/qdrant/storage

  web:
    build: .
    environment:
      - APP_QDRANT__MODE=server
      - APP_QDRANT__HOST=qdrant
      - APP_QDRANT__PORT=6333
    depends_on:
      - qdrant

In this configuration, the web service connects to the qdrant container over the Docker network. The VectorDbContext automatically initializes the collection on first startup.

For a simpler single-container deployment without a separate Qdrant service, use local mode instead:

services:
  web:
    build: .
    environment:
      - APP_QDRANT__MODE=local
      - APP_QDRANT__LOCAL_PATH=/data/qdrant
    volumes:
      - ./local_data:/data

Summary

• Server mode connects to external Qdrant instances via AsyncQdrantClient(host=...) and requires APP_QDRANT__HOST configuration
• Local mode stores vectors in a file path specified by APP_QDRANT__LOCAL_PATH using embedded Qdrant
• Memory mode creates temporary RAM-only storage using AsyncQdrantClient(":memory:") for testing
• All modes are controlled by the APP_QDRANT__MODE environment variable processed through app/config.py
• The VectorDbContext class in app/Services/vector_db_context.py handles client instantiation and collection initialization automatically

Frequently Asked Questions

How do I switch from server mode to local file storage?

Set APP_QDRANT__MODE=local and specify a directory with APP_QDRANT__LOCAL_PATH. The application will migrate to embedded storage automatically, though existing data in the external server will not transfer automatically—you must re-index your images.

Does memory mode persist any data to disk?

No. Memory mode uses AsyncQdrantClient(":memory:") which keeps all vectors strictly in RAM. When the Neko Image Gallery process terminates, all indexed images and search data disappear immediately. Use this only for testing or ephemeral demonstrations.

Where are the default Qdrant settings defined in the codebase?

Default values reside in app/config.py within the QdrantSettings class (lines 11-28). The mode selection logic and client instantiation occur in app/Services/vector_db_context.py (lines 31-44), where a match statement selects the appropriate AsyncQdrantClient constructor based on config.qdrant.mode.

Can I use Qdrant Cloud with this configuration?

Yes. Set APP_QDRANT__MODE=server, point APP_QDRANT__HOST to your Qdrant Cloud endpoint (e.g., xxx.europe-west3-0.gcp.cloud.qdrant.io), and provide your API key via APP_QDRANT__API_KEY. The VectorDbContext will connect using the standard HTTP/gRPC client with authentication headers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}