Environment variables

OpenRAG's .env file is the primary configuration file for OpenRAG. Environment variables in .env always take precedence over other sources.

For deployments managed with the Terminal User Interface (TUI), this file is located at ~/.openrag/tui, and it can be created automatically during installation.

For self-managed deployments, this file can be located at the root of your OpenRAG project directory or referenced from another location.

For an example, see .env.example in the OpenRAG repository.

tip

OpenRAG's Docker Compose files are populated automatically using values from the .env file, so you don't need to edit the Docker Compose files manually.

If a variable isn't set, OpenRAG uses default or fallback values where available. Not all variables have default values, and errors can occur if required variables aren't set. Default values can be found in the reference tables on this page and in config_manager.py, settings.py, and logging_config.py.

You can temporarily set Langflow variables at runtime. However, these temporary overrides don't overlap with most OpenRAG environment variables. The only exceptions are flow-level Langflow settings, such as the language model used in a flow.

Edit the .env file

During installation, an initial .env file is created automatically or manually. You can edit this file to change OpenRAG configuration settings after installation.

Each OpenRAG environment variable is either mutable or immutable. This determines the actions you must take to apply changes after editing the .env file:

• Mutable environment variables: You can apply changes to mutable environment variables by stopping and restarting the OpenRAG services after editing the .env file.

• Immutable environment variables: You must redeploy OpenRAG with your modified .env file if you change immutable environment variables.

Model provider settings

Configure which models and providers OpenRAG uses to generate text and embeddings. You only need to provide credentials for the providers you are using in OpenRAG.

These variables are initially set during the application onboarding process. Some of these variables are immutable and can only be changed by redeploying OpenRAG, as explained in Set environment variables.

Variable	Default	Description
EMBEDDING_MODEL	text-embedding-3-small	Embedding model for generating vector embeddings for documents in the knowledge base and similarity search queries. Can be changed after the application onboarding process. Accepts one or more models.
LLM_MODEL	gpt-4o-mini	Language model for language processing and text generation in the Chat feature.
MODEL_PROVIDER	openai	Model provider, as one of openai, watsonx, ollama, or anthropic.
ANTHROPIC_API_KEY	Not set	API key for the Anthropic language model provider.
OPENAI_API_KEY	Not set	API key for the OpenAI model provider, which is also the default model provider.
OLLAMA_ENDPOINT	Not set	Custom provider endpoint for the Ollama model provider.
WATSONX_API_KEY	Not set	API key for the IBM watsonx.ai model provider.
WATSONX_ENDPOINT	Not set	Custom provider endpoint for the IBM watsonx.ai model provider.
WATSONX_PROJECT_ID	Not set	Project ID for the IBM watsonx.ai model provider.

Document processing settings

Control how OpenRAG processes and ingests documents into your knowledge base.

Variable	Default	Description
CHUNK_OVERLAP	200	Overlap between chunks.
CHUNK_SIZE	1000	Text chunk size for document processing.
DISABLE_INGEST_WITH_LANGFLOW	false	Disable Langflow ingestion pipeline.
DOCLING_OCR_ENGINE	Set by OS	OCR engine for document processing. For macOS, ocrmac. For any other OS, easyocr.
OCR_ENABLED	false	Enable OCR for image processing.
OPENRAG_DOCUMENTS_PATH	~/.openrag/documents	The local documents path for ingestion.
PICTURE_DESCRIPTIONS_ENABLED	false	Enable picture descriptions.

Langflow settings

Configure the OpenRAG Langflow server's authentication, contact point, and built-in flow definitions.

info

The LANGFLOW_SUPERUSER_PASSWORD is set in your .env file, and this value determines the default values for several other Langflow authentication variables.

If the LANGFLOW_SUPERUSER_PASSWORD variable isn't set, then the Langflow server starts without authentication enabled.

For better security, it is recommended to set LANGFLOW_SUPERUSER_PASSWORD so the Langflow server starts with authentication enabled.

Variable	Default	Description
LANGFLOW_AUTO_LOGIN	Determined by LANGFLOW_SUPERUSER_PASSWORD	Whether to enable auto-login mode for the Langflow visual editor and CLI. If LANGFLOW_SUPERUSER_PASSWORD isn't set, then LANGFLOW_AUTO_LOGIN is True and auto-login mode is enabled. If LANGFLOW_SUPERUSER_PASSWORD is set, then LANGFLOW_AUTO_LOGIN is False and auto-login mode is disabled. Langflow API calls always require authentication with a Langflow API key regardless of the auto-login setting.
LANGFLOW_ENABLE_SUPERUSER_CLI	Determined by LANGFLOW_SUPERUSER_PASSWORD	Whether to enable the Langflow CLI langflow superuser command. If LANGFLOW_SUPERUSER_PASSWORD isn't set, then LANGFLOW_ENABLE_SUPERUSER_CLI is True and superuser accounts can be created with the Langflow CLI. If LANGFLOW_SUPERUSER_PASSWORD is set, then LANGFLOW_ENABLE_SUPERUSER_CLI is False and the langflow superuser command is disabled.
LANGFLOW_NEW_USER_IS_ACTIVE	Determined by LANGFLOW_SUPERUSER_PASSWORD	Whether new Langflow user accounts are active by default. If LANGFLOW_SUPERUSER_PASSWORD isn't set, then LANGFLOW_NEW_USER_IS_ACTIVE is True and new user accounts are active by default. If LANGFLOW_SUPERUSER_PASSWORD is set, then LANGFLOW_NEW_USER_IS_ACTIVE is False and new user accounts are inactive by default.
LANGFLOW_PUBLIC_URL	http://localhost:7860	Public URL for the Langflow instance. Forms the base URL for Langflow API calls and other interfaces with your OpenRAG Langflow instance.
LANGFLOW_KEY	Automatically generated	A Langflow API key to run flows with Langflow API calls. Because Langflow API keys are server-specific, allow OpenRAG to generate this key initially. You can create additional Langflow API keys after deploying OpenRAG.
LANGFLOW_SECRET_KEY	Automatically generated	Secret encryption key for Langflow internal operations. It is recommended to generate your own Langflow secret key for this variable. If this variable isn't set, then Langflow generates a secret key automatically.
LANGFLOW_SUPERUSER	admin	Username for the Langflow administrator user.
LANGFLOW_SUPERUSER_PASSWORD	Not set	Langflow administrator password. If this variable isn't set, then the Langflow server starts without authentication enabled. It is recommended to set LANGFLOW_SUPERUSER_PASSWORD so the Langflow server starts with authentication enabled.
LANGFLOW_URL	http://localhost:7860	URL for the Langflow instance.
LANGFLOW_CHAT_FLOW_ID, LANGFLOW_INGEST_FLOW_ID, NUDGES_FLOW_ID	Built-in flow IDs	These variables are set automatically to the IDs of the chat, ingestion, and nudges flows. The default values are found in .env.example. Only change these values if you want to replace a built-in flow with your own custom flow. The flow JSON must be present in your version of the OpenRAG codebase. For example, if you deploy self-managed services, you can add the flow JSON to your local clone of the OpenRAG repository before deploying OpenRAG.
SYSTEM_PROMPT	You are a helpful AI assistant with access to a knowledge base. Answer questions based on the provided context.	System prompt instructions for the agent driving the Chat flow.

OAuth provider settings

Configure OAuth providers and external service integrations.

Variable	Default	Description
AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY	Not set	Enable access to AWS S3 with an AWS OAuth app integration.
GOOGLE_OAUTH_CLIENT_ID GOOGLE_OAUTH_CLIENT_SECRET	Not set	Enable the Google OAuth client integration. You can generate these values in the Google Cloud Console.
MICROSOFT_GRAPH_OAUTH_CLIENT_ID MICROSOFT_GRAPH_OAUTH_CLIENT_SECRET	Not set	Enable the Microsoft Graph OAuth client integration by providing Azure application registration credentials for SharePoint and OneDrive.
WEBHOOK_BASE_URL	Not set	Base URL for OAuth connector webhook endpoints. If this variable isn't set, a default base URL is used.

OpenSearch settings

Configure OpenSearch database authentication.

Variable	Default	Description
OPENSEARCH_HOST	localhost	OpenSearch instance host.
OPENSEARCH_PORT	9200	OpenSearch instance port.
OPENSEARCH_USERNAME	admin	OpenSearch administrator username.
OPENSEARCH_PASSWORD	Must be set at start up	Required. OpenSearch administrator password. Must adhere to the OpenSearch password complexity requirements. You must set this directly in the .env or in the TUI's Basic/Advanced Setup.

System settings

Configure general system components, session management, and logging.

Variable	Default	Description
LANGFLOW_KEY_RETRIES	15	Number of retries for Langflow key generation.
LANGFLOW_KEY_RETRY_DELAY	2.0	Delay between retries in seconds.
LANGFLOW_VERSION	OPENRAG_VERSION	Langflow Docker image version. By default, OpenRAG uses the OPENRAG_VERSION for the Langflow Docker image version.
LOG_FORMAT	Not set	Set to json to enabled JSON-formatted log output. If this variable isn't set, then the default logging format is used.
LOG_LEVEL	INFO	Logging level. Can be one of DEBUG, INFO, WARNING, or ERROR. DEBUG provides the most detailed logs but can impact performance.
MAX_WORKERS	1	Maximum number of workers for document processing.
OPENRAG_VERSION	latest	The version of the OpenRAG Docker images to run. For more information, see Upgrade OpenRAG
SERVICE_NAME	openrag	Service name for logging.
SESSION_SECRET	Automatically generated	Session management.