Generic RAG backend environment variables

This reference lists every environment variable of the Generic RAG backend, with its default and behavior. It is for platform engineers who deploy the backend. For registration and background jobs, see Configuration.

Version scope

Defaults below are checked against backend 0.3.3, in settings.py, the other modules that read the environment, and the Dockerfile. The upstream README marks ELASTICSEARCH_USERNAME and ELASTICSEARCH_PASSWORD optional. In the code, both are required once ELASTICSEARCH_URL is set.

The backend also loads a .env file from its working directory at startup. A variable already set in the environment takes precedence over the file. An invalid value stops the backend at startup, with the validation error in its log.

DIAL Core

Variable	Required	Default	Description
`DIAL_URL`	Yes	—	The DIAL Core URL. The backend reads application properties, files, and models there.
`DIAL_API_KEY`	No	—	An API key for background jobs. Without it, indexing runs during the upload request, and channel archives are unavailable.
`DIAL_PUBLIC_URL`	No	`DIAL_URL`	The DIAL Core URL that the channel API description at `/docs` shows as its server

File cache

Variable	Default	Description
`IN_MEMORY_CACHE_ENABLED`	`true`	Caches the content of files the backend writes to and reads from DIAL Core, such as documents and page images. A file is cached by its URL and ETag.
`IN_MEMORY_CACHE_CAPACITY`	`128MiB`	The cache size of each process, in bytes or as a size such as `1GiB`. A larger cache needs more pod memory.

PostgreSQL

Variable	Required	Default	Description
`DB_HOST`	Yes	—	The database host
`DB_PORT`	No	`5432`	The database port
`DB_NAME`	Yes	—	The database name. It needs the `vector` extension.
`DB_USERNAME`	Yes	—	The database user. It creates the backend's tables at startup.
`DB_PASSWORD`	One of these two	—	The password
`DB_MSI_ENABLED`	One of these two	`false`	`true` signs in with an Azure managed identity token instead of a password. It wins over `DB_PASSWORD`.
`DB_MSI_SCOPE`	No	`https://ossrdbms-aad.database.windows.net/.default`	The token scope for managed identity sign-in

With managed identity, the backend refreshes the token 2 minutes before it expires.

Elasticsearch

Variable	Required	Default	Description
`ELASTICSEARCH_URL`	No	—	Turns on the `elastic` storage backend. The backend uses the URL's scheme, host, and port, and ignores its path.
`ELASTICSEARCH_USERNAME`	With the URL	—	The user, for basic authentication
`ELASTICSEARCH_PASSWORD`	With the URL	—	The password
`ELASTICSEARCH_INDEX_PREFIX`	No	—	A prefix for the names of the backend's Elasticsearch indexes

When several Generic RAG deployments share one Elasticsearch, give each a unique ELASTICSEARCH_INDEX_PREFIX, as the upstream README requires. A prefix must be lowercase and at most 64 bytes. It can't contain \ / * ? " < > | , # : or spaces, start with -, _, or +, or be . or ...

The backend checks the connection at startup, up to 5 times. When all attempts fail, it doesn't start.

Chat responses

Variable	Default	Description
`ENABLE_DEBUG_STAGES`	`false`	Shows `[DEBUG]` stages: the channel and request configuration, each index's results, the raw LLM output, token usage, and stack traces of errors
`ENABLE_ANNOTATIONS`	`true`	Cites documents as annotations, which DIAL Chat 1.x shows on the answer. `false` cites them as attachments, with `[n]` markers in the text.
`ENABLE_QUOTE_THUMBNAILS`	`false`	Adds thumbnails of image chunks to citation attachments. It has no effect while `ENABLE_ANNOTATIONS` is `true`.

Values true, yes, and 1 turn a setting on, and false, no, and 0 turn it off.

MCP

Variable	Default	Description
`MCP_GET_PAGES_LIMIT`	`10`	The most pages one `get_pages` call returns. It must be above `0`.

Built-in embeddings

Variable	Default	Description
`BGE_EMBEDDING_MODEL_PATH`	`/home/appuser/bge-small-en` in the image	The `epam/bge-small-en` model behind the built-in embeddings endpoint. Outside the image, the default is the model's Hugging Face name.

Logging

Variable	Default	Description
`LOG_LEVEL`	`INFO`	The log level
`LOG_USE_COLORS`	`false`	Colors the log output
`DIAL_SDK_LOG`	`WARNING`	The level of the DIAL SDK's own logger

Log lines show the trace and span IDs of the request in brackets.

Observability

The backend names itself generic-rag in telemetry. It uses the DIAL SDK 0.40.0, whose OTLP exporters use gRPC and read the standard OTEL_EXPORTER_OTLP_* variables.

Variable	Default	Description
`OTEL_TRACES_EXPORTER`	A value that exports nothing	`otlp` exports traces. When it's unset, the backend sets a value that exports nothing.
`OTEL_METRICS_EXPORTER`	Unset	Comma-separated. `otlp` pushes metrics, and `prometheus` serves them on `OTEL_EXPORTER_PROMETHEUS_PORT`.
`OTEL_LOGS_EXPORTER`	Unset	Comma-separated. `otlp` exports log records, and `console` writes them to stderr as JSON lines.
`OTEL_EXPORTER_PROMETHEUS_PORT`	`9464`	The Prometheus port
`OTEL_PYTHON_LOG_CORRELATION`	`true`, set by the backend	Adds trace context to log records

DIAL SDK

Variable	Default	Description
`DIAL_SDK_HEADERS_TO_PROXY`	Unset	Comma-separated header names. The DIAL SDK copies these headers of the incoming request into the backend's HTTP calls to `DIAL_URL`.

Set by the image

Variable	Value	Purpose
`FASTMCP_LOG_ENABLED`	`false`	Turns off FastMCP's own logging setup
`DO_NOT_TRACK`	`true`	Turns off usage tracking in the `unstructured` library
`NUMBA_CACHE_DIR`	`/tmp/numba_cache`	The cache folder of the `numba` library

Version scope​

DIAL Core​

File cache​

PostgreSQL​

Elasticsearch​

Chat responses​

MCP​

Built-in embeddings​

Logging​

Observability​

DIAL SDK​

Set by the image​

Further reading​