Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/app/main.go
• internal/qdrant/client.go
• internal/embeddings/openai.go
• internal/embeddings/ollama.go
• internal/search/service.go
• setup-ollama.md

The MauQNotes application is configured primarily through environment variables, which are loaded from a .env file at runtime. This approach allows for flexible deployment and easy switching between different service providers for embeddings (like Ollama and OpenAI) and vector storage (Qdrant).

The main configurable components are the Qdrant vector database client and the embedding generation service. The configuration determines which embedding model to use, its corresponding vector dimensions, and the connection details for the required services.

Environment Variables

All configuration is managed via environment variables. The application uses the godotenv library to load these variables from a .env file in the project root.

Sources: internal/search/service.go:13, internal/qdrant/client.go:72, internal/embeddings/ollama.go:21, internal/embeddings/openai.go:23

The following table summarizes the key environment variables used by the application:

Variable	Description	Default Value	Used In
EMBEDDING_MODEL	Specifies the embedding model to use for generating vectors.	nomic-embed-text	internal/search/service.go, internal/embeddings/ollama.go, internal/embeddings/openai.go
QDRANT_URL	The base URL for the Qdrant database instance.	(none)	internal/qdrant/client.go
QDRANT_API_KEY	The API key for authenticating with the Qdrant instance.	(none)	internal/qdrant/client.go
QDRANT_COLLECTION	The name of the collection within Qdrant to store the note vectors.	(none)	internal/qdrant/client.go
OLLAMA_URL	The URL for the Ollama service API, used for generating embeddings.	http://localhost:11434	internal/embeddings/ollama.go
OPENAI_API_KEY	The API key for authenticating with the OpenAI embeddings API.	(none)	internal/embeddings/openai.go

System Initialization Flow

The application initializes its services by reading the environment variables to configure the embedding model and the Qdrant client.

The diagram below shows the configuration loading and initialization flow.

Embedding Service Configuration

The choice of embedding model and provider is central to the application's functionality. This is controlled by the EMBEDDING_MODEL variable.

Sources: internal/search/service.go:14-17, internal/embeddings/ollama.go:28-31, internal/embeddings/openai.go:25

Model and Vector Dimensions

The search.Init() function determines the required vector dimension for the Qdrant collection based on the selected EMBEDDING_MODEL. This ensures that the collection is created with the correct size for the chosen model's output.

Sources: internal/search/service.go:12-31

EMBEDDING_MODEL Value	Vector Dimension
nomic-embed-text (default)	768
all-minilm	384
mxbai-embed-large	512
(any other value)	768

Sources: internal/search/service.go:21-29, setup-ollama.md

Embedding Providers

The application can generate embeddings using either a local Ollama instance or the remote OpenAI API. Currently, the search service is hardcoded to use embeddings.FromOllama.

Sources: internal/search/service.go:43

Ollama Configuration

The FromOllama function handles communication with a local Ollama service.

• It reads the OLLAMA_URL environment variable. If not set, it defaults to http://localhost:11434.
• It reads the EMBEDDING_MODEL environment variable. If not set, it defaults to nomic-embed-text.
• It sends a POST request to the /api/embeddings endpoint of the Ollama service.

Sources: internal/embeddings/ollama.go:20-42

The sequence diagram below illustrates how an embedding is generated via Ollama.

OpenAI Configuration

Although not currently used by the search service, the FromOpenAI function is available for generating embeddings via the OpenAI API.

• It requires OPENAI_API_KEY and EMBEDDING_MODEL to be set.
• It sends a POST request to https://api.openai.com/v1/embeddings.
• The Authorization header is set to Bearer <OPENAI_API_KEY>.

Sources: internal/embeddings/openai.go:23-36

Qdrant Client Configuration

The qdrant.Client is responsible for all communication with the Qdrant vector database. Its configuration is handled by the qdrant.New() constructor.

Sources: internal/qdrant/client.go:71-77

Connection Parameters

The client is configured using the following environment variables:

• QDRANT_URL: The full URL of the Qdrant instance.
• QDRANT_API_KEY: The API key for authentication (optional).
• QDRANT_COLLECTION: The name of the collection to use.

The New() function reads these variables and initializes a Client struct.

// internal/qdrant/client.go:71-77
func New() *Client {
	_ = godotenv.Load()
	return &Client{
		BaseUrl:    os.Getenv("QDRANT_URL"),
		APIKey:     os.Getenv("QDRANT_API_KEY"),
		Collection: os.Getenv("QDRANT_COLLECTION"),
	}
}

Sources: internal/qdrant/client.go:71-77

Client Validation

Before any operation (e.g., CreateCollectionIfNotExists, Upsert, Search), the client runs a validation check. This ensures that essential configuration is present and correctly formatted.

The validate() method checks for:

1. QDRANT_URL is not empty.
2. QDRANT_URL starts with http:// or https://.
3. QDRANT_COLLECTION is not empty.

If any of these checks fail, the operation returns an error.

Sources: internal/qdrant/client.go:80-89