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

> Learn to configure Qdrant in server, local, or memory mode for Neko Image Gallery using the APP_QDRANT__MODE variable for flexible vector storage options.

- Repository: [EdgeNeko/nekoimagegallery](https://github.com/hv0905/nekoimagegallery)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/hv0905/nekoimagegallery/blob/main/app/config.py).

## Understanding Qdrant Configuration Architecture

The configuration system uses Pydantic settings defined in [`app/config.py`](https://github.com/hv0905/nekoimagegallery/blob/main/app/config.py) (lines 11-28) to validate and load Qdrant parameters. When the application initializes, `VectorDbContext` in [`app/Services/vector_db_context.py`](https://github.com/hv0905/nekoimagegallery/blob/main/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`](https://github.com/hv0905/nekoimagegallery/blob/main/app/Services/vector_db_context.py), the client instantiation uses host, port, and authentication parameters:

```python
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:

```bash
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:

```python
AsyncQdrantClient(path=config.qdrant.local_path)

```

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

```bash
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`](https://github.com/hv0905/nekoimagegallery/blob/main/app/Services/vector_db_context.py) uses the special `:memory:` string:

```python
AsyncQdrantClient(":memory:")

```

Activate memory mode with a single environment variable:

```bash
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:

```yaml
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:

```yaml
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`](https://github.com/hv0905/nekoimagegallery/blob/main/app/config.py)
- The `VectorDbContext` class in [`app/Services/vector_db_context.py`](https://github.com/hv0905/nekoimagegallery/blob/main/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`](https://github.com/hv0905/nekoimagegallery/blob/main/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`](https://github.com/hv0905/nekoimagegallery/blob/main/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.