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.
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 and apply configuration changes
During installation, you prepare an initial .env file.
For TUI-managed deployments, this file is created automatically.
For self-managed deployments, you create this file manually.
After installation, you can edit the .env file to change your OpenRAG configuration.
For TUI-managed deployments, many environment variables can be set in the TUI's When you save the changes and restart the OpenRAG services, the .env is updated automatically.
Most OpenRAG environment variables are mutable, and you can apply changes to these settings by stopping and restarting the OpenRAG services after editing the .env file.
If a change doesn't take effect after restarting the services, then the variable is immutable, and you must redeploy OpenRAG with your modified .env file.
This is typically only required for critical configuration changes that affect the core OpenRAG infrastructure.
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.
| Variable | Default | Description |
|---|---|---|
EMBEDDING_PROVIDER | openai | Embedding model provider, as one of openai, watsonx, or ollama. |
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. |
LLM_PROVIDER | openai | Language model provider, as one of openai, watsonx, ollama, or anthropic. |
LLM_MODEL | gpt-4o-mini | Language model for language processing and text generation in the Chat feature. Can be changed after the application onboarding process. |
ANTHROPIC_API_KEY | Not set | API key for the Anthropic 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
Controls some aspects of how OpenRAG processes and ingests documents into your knowledge base.
For the embedding model and Docling engine variables that you can set on the OpenRAG Settings page, see Configure ingestion.
For Langflow flow IDs and Langflow timeout settings, see Langflow settings.
| Variable | Default | Description |
|---|---|---|
DISABLE_INGEST_WITH_LANGFLOW | false | Disable Langflow ingestion pipeline if you don't want to use the default Docling Serve instance. |
DOCLING_SERVE_URL | http://HOST_IP:5001 | URL for the Docling Serve instance. By default, OpenRAG starts a local docling serve process and auto-detects the host. To use your own local or remote Docling Serve instance, set this variable to the full path to the target instance. The service must run on port 5001. |
OPENRAG_DOCUMENTS_PATH | ~/.openrag/documents | The local documents path for ingestion. |
HOST_DOCKER_INTERNAL | host.docker.internal | Host address for accessing services running on the host machine from within Docker containers. This is used to connect to the local Docling Serve instance started by OpenRAG. If your system uses a different hostname for this purpose, set this variable accordingly. |
INGESTION_TIMEOUT | 3600 | Document ingestion timeout limit in seconds for each file. Increase this value if you experience timeouts when ingesting very large documents. Must be greater than or equal to LANGFLOW_TIMEOUT. |
UPLOAD_BATCH_SIZE | 25 | When ingesting folders, set the maximum number of files to ingest per batch. Each batch is an ingestion task. Increase this value to ingest more files per batch. If this value is too high, performance issues can occur. |
Langflow settings
Configure the OpenRAG Langflow server's authentication, contact point, and built-in flow definitions.
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_PORT | 7860 | Host port for the Langflow service. Change this if port 7860 is already in use on your system. If you change this, you must also set LANGFLOW_PUBLIC_URL to the new port. |
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. Can also be set in the TUI's Advanced Setup. |
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_CHAT_FLOW_ID, LANGFLOW_INGEST_FLOW_ID, NUDGES_FLOW_ID, LANGFLOW_URL_INGEST_FLOW_ID | Built-in flow IDs | These variables are set automatically to the IDs of the chat, Docling ingestion, URL 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. |
LANGFUSE_SECRET_KEY | Not set | Optional Langfuse secret key to enable the Langflow integration with Langfuse. |
LANGFUSE_PUBLIC_KEY | Not set | Optional Langfuse public key to enable the Langflow integration with Langfuse. |
LANGFUSE_HOST | Not set | Leave empty for Langfuse Cloud. Required for self-hosted Langfuse deployments if LANGFUSE_SECRET_KEY and LANGFUSE_PUBLIC_KEY are set. The address must be relative to the OpenRAG container deployment. For example, http://localhost:3002 or http://host.docker.internal:3000. |
LANGFLOW_TIMEOUT | 2400 | Total Langflow HTTP timeout limit in seconds. Increase this value if you experience timeouts when ingesting very large PDFs. See also INGESTION_TIMEOUT. |
LANGFLOW_CONNECT_TIMEOUT | 30 | Langflow HTTP connection timeout limit in seconds. Increase this value if you experience timeouts when ingesting very large PDFs. |
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_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. This variable is currently inactive and for information purposes only. |
OAuth and cloud storage connector settings
Use these variables to enable OAuth mode and configure cloud storage connectors.
Additional configuration is required for these features. For more information, see Configure connectors.
| Variable | Default | Description |
|---|---|---|
AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEY | Not set | Authorize OpenRAG to ingest documents from AWS S3 with an AWS OAuth app integration. |
GOOGLE_OAUTH_CLIENT_IDGOOGLE_OAUTH_CLIENT_SECRET | Not set | Enable OAuth mode and the Google Drive cloud storage connector with the Google OAuth client integration. You can generate these values in the Google Cloud Console. |
MICROSOFT_GRAPH_OAUTH_CLIENT_IDMICROSOFT_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 | Optional base URL for OAuth connector webhook endpoints. If not set, a default base URL is used. This variable is required to enable automatic cloud storage ingestion. Can also be set in the TUI's Advanced Setup. |
OpenSearch settings
Configure OpenSearch database authentication.
| Variable | Default | Description |
|---|---|---|
OPENSEARCH_DATA_PATH | ./opensearch-data | The path where OpenRAG creates your OpenSearch index data. This persists through updates. |
OPENSEARCH_PASSWORD | Not set | 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. |
OPENSEARCH_INDEX_NAME | documents | The name of the OpenSearch index. |
OPENSEARCH_HOST | localhost | OpenSearch service host. |
OPENSEARCH_PORT | 9200 | OpenSearch service port. |
OPENSEARCH_USERNAME | admin | OpenSearch administrator username. |
System settings
Configure general system components, session management, and logging.
| Variable | Default | Description |
|---|---|---|
FRONTEND_PORT | 3000 | Host port for the OpenRAG frontend web interface. Change this if port 3000 is already in use on your system. |
OPENRAG_VERSION | latest | The version of the OpenRAG Docker images to run. For more information, see Upgrade OpenRAG |
NEXT_ALLOWED_DEV_ORIGINS | http://localhost:3000 | Only used when running OpenRAG in development mode. Accepts a comma-separated list of hostnames to allow additional origins to make requests to the Next.js development server. |
MAX_WORKERS | min(4, CPU_COUNT // 2) | Number of Backend worker processes for concurrent request handling. Be mindful of hardware limitations to avoid overtaxing system resources. |
LANGFLOW_WORKERS | 1 | Number of Langflow worker processes for concurrent request handling. Be mindful of hardware limitations to avoid overtaxing system resources. |
DOCLING_WORKERS | 1 | Number of Docling worker processes for concurrent request handling. Be mindful of hardware limitations to avoid overtaxing system resources. |
ACCESS_LOG | true | Whether to enable access logging for OpenRAG services, such as INFO: 127.0.0.1:45132 - "GET /tasks HTTP/1.1" 200 OK. Access logs provide information about incoming requests, and they can be useful for monitoring and debugging. |
LOG_FORMAT | json | Set to json to enable JSON-formatted log output, or text for standard text logs. |
LOG_LEVEL | INFO | Logging level. Can be one of DEBUG, INFO, WARNING, ERROR, or CRITICAL. DEBUG provides the most detailed logs but can impact performance. |
SERVICE_NAME | openrag | Service name used in log entries. |
SESSION_SECRET | Automatically generated | Secret key for session management. If not provided, a secure random key is generated automatically. |