OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
# Ingestion Configuration
# Set to true to disable Langflow ingestion and use traditional OpenRAG processor
# If unset or false, Langflow pipeline will be used (default: upload -> ingest -> delete)
DISABLE_INGEST_WITH_LANGFLOW=false
# What to do when the embedding model rejects a chunk or query as longer than
# its input limit (for example 512 tokens).
# average (default): embed the text in smaller pieces and use the
# length-weighted average of their vectors, so ingestion continues.
# error: fail the request; the file reports that a section is too long.
# OPENRAG_EMBEDDING_OVERFLOW_POLICY=average
# Set to false to skip ingesting OpenRAG sample docs during onboarding
# Default: true
INGEST_SAMPLE_DATA=true
# Default OpenRAG docs source for sample ingestion during onboarding.
# - url: crawl DEFAULT_DOCS_URL using URL ingestion flow
# - files: ingest files from OPENRAG_DOCUMENTS_PATH
DEFAULT_DOCS_INGEST_SOURCE=url
# URL used when DEFAULT_DOCS_INGEST_SOURCE=url
DEFAULT_DOCS_URL=https://www.openr.ag/
# How many levels deep to crawl when DEFAULT_DOCS_INGEST_SOURCE=url (default: 2)
# DEFAULT_DOCS_CRAWL_DEPTH=2
# Check for newer OpenRAG docs and update knowledge on every startup.
# Default: false (manual fetch remains available in UI)
FETCH_OPENRAG_DOCS_AT_STARTUP=false
# Langflow HTTP timeout configuration (in seconds)
# For large documents (300+ pages), ingestion can take 30+ minutes
# Increase these values if you experience timeouts with very large PDFs
# Default: 2400 seconds (40 minutes) total timeout, 30 seconds connection timeout
# LANGFLOW_TIMEOUT=2400
# LANGFLOW_CONNECT_TIMEOUT=30
# OPTIONAL: Per-file processing timeout for document ingestion tasks (in seconds)
# Should be >= LANGFLOW_TIMEOUT to allow long-running ingestion to complete
# Default: 3600 seconds (60 minutes) total timeout
# INGESTION_TIMEOUT=3600
# OPTIONAL: OpenSearch JWT TTL for per-user document security tokens (in seconds)
# Default: INGESTION_TIMEOUT + 300 seconds
# OPENRAG_OPENSEARCH_JWT_TTL=3900
# OPTIONAL: Maximum number of files to upload / ingest (in batch) per task when adding knowledge via folder
# Default: 25
# UPLOAD_BATCH_SIZE=25
# OPTIONAL: Largest accepted upload, in mebibytes. Oversized files are refused
# at upload time. This does not raise the body limit on the proxy in front of
# docling-serve. If that proxy cannot be changed, set this to its real limit.
# Default: 100
# OPENRAG_MAX_UPLOAD_MB=100
# make one like so https://docs.langflow.org/api-keys-and-authentication#langflow-secret-key
LANGFLOW_SECRET_KEY=
# flow ids for chat and ingestion flows
LANGFLOW_CHAT_FLOW_ID=1098eea1-6649-4e1d-aed1-b77249fb8dd0
LANGFLOW_INGEST_FLOW_ID=5488df7c-b93f-4f87-a446-b67028bc0813
LANGFLOW_URL_INGEST_FLOW_ID=72c3d17c-2dac-4a73-b48a-6518473d7830
# Ingest flow using docling
# LANGFLOW_INGEST_FLOW_ID=1402618b-e6d1-4ff2-9a11-d6ce71186915
NUDGES_FLOW_ID=ebc01d31-1976-46ce-a385-b0240327226c
# Backend bind port for local `make backend`.
OPENRAG_BACKEND_PORT=8000
# Optional path prefix used when serving the complete Next.js frontend below a
# sub-path (for example https://example.com/openrag-fe). The frontend container
# applies this value at startup, so changing it does not require an image rebuild.
# OPENRAG_FRONTEND_BASE_PATH=/openrag-fe
# URL Docker-hosted services use to call the backend in host-backend mode.
# If unset, auto-derived from OPENRAG_BACKEND_PORT. Only set this explicitly
# if you need to override the auto-derived value (e.g., custom hostname).
# OPENRAG_BACKEND_INTERNAL_URL=http://openrag-backend:8000
# --- CORS -------------------------------------------------------------------
# Comma-separated list of origins allowed to make cross-origin requests
# (e.g. "https://app.example.com,https://admin.example.com").
# Unset → defaults to http://localhost:3000. Set to "" to disable CORS entirely.
CORS_ALLOWED_ORIGINS=http://localhost:3000
# --- Backend ingestion-callback proxy router --------------------------------
# When enabled, a tiny standalone uvicorn app is started in the same process as
# the backend (its own port) that proxies ONLY the Langflow ingest callback
# (POST /internal/ingest/chunks) to the real backend. Langflow is then pointed
# at this router instead of the backend internal URL, narrowing the surface
# Langflow can reach. Disabled by default.
# OPENRAG_BACKEND_ROUTER_ENABLE=false
# Port the router listens on (inside the backend container/pod).
# OPENRAG_BACKEND_ROUTER_PORT=8100
# OPENRAG_BACKEND_ROUTER_HOST=0.0.0.0
# Base URL Langflow calls back to. Defaults to the backend host on the router
# port (derived from OPENRAG_BACKEND_INTERNAL_URL); set only if the router is
# fronted by a separate Service/ingress.
# OPENRAG_BACKEND_ROUTER_URL=
# Upstream the router forwards callbacks to. The router is co-located with the
# backend (same process), so it defaults to loopback on the backend's port
# (port derived from OPENRAG_BACKEND_INTERNAL_URL, host forced to 127.0.0.1).
# Set only to override the upstream entirely.
# OPENRAG_BACKEND_ROUTER_UPSTREAM_URL=http://127.0.0.1:8000
# OpenAI-compatible LLM proxy Langflow calls (must end with /v1). Defaults to
# OPENRAG_BACKEND_INTERNAL_URL/v1. Override only if Langflow cannot reach that host.
# OPENRAG_LLM_PROXY_URL=http://openrag-backend:8000/v1
# TTL for the short-lived Langflow LLM hop token (OPENRAG_LLM_TOKEN Langflow
# sends to /v1/chat/completions and /v1/embeddings). Defaults to the
# ingest-callback TTL.
# LANGFLOW_LLM_PROXY_TTL_SECONDS=3900
# Base64 AES-256-GCM Master Encryption Key
# If not provided, OpenRAG will automatically generate a secure 32-byte key when you run the TUI or CLI wizard.
# If completely unset during normal execution, the master encryption system will remain inactive.
# This key is required to decrypt API credentials stored in local databases and provider indices.
OPENRAG_ENCRYPTION_KEY=
# Identifier for AAD tenant binding.
# Used to verify that encrypted files belong to the expected tenant.
# Default: openrag
OPENRAG_TENANT_ID=openrag
# If set to true, the application will fail to start if any critical
# prerequisites are not met (e.g. master encryption key missing).
# Default: false
OPENRAG_ENFORCE_PREREQUISITES=false
# Set a strong admin password for OpenSearch; a bcrypt hash is generated at
# container startup from this value. Do not commit real secrets.
# must match the hashed password in secureconfig, must change for secure deployment!!!
# NOTE: if you set this by hand, it must be a complex password:
# The password must contain at least 8 characters, and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character.
OPENSEARCH_PASSWORD=
# Path to persist Langflow database and state (flows, credentials, settings)
# Without this volume, flow edits will be lost on container restart
# Default: ./langflow-data
LANGFLOW_DATA_PATH=./langflow-data
# Langflow database URL. Defaults to SQLite stored in LANGFLOW_DATA_PATH.
# Override with a PostgreSQL URL for production deployments, e.g.:
# LANGFLOW_DATABASE_URL=postgresql://user:pass@host:5432/langflow
LANGFLOW_DATABASE_URL=sqlite:////app/langflow-data/langflow.db
# OpenSearch Connection
# OPENSEARCH_HOST=opensearch
# OPENSEARCH_PORT=9200
# OPENSEARCH_DASHBOARDS_PORT=5601
# OPENSEARCH_PERF_PORT=9600
OPENSEARCH_USERNAME=admin
# Disable the OpenSearch node-count readiness gate for single-node local setups.
OPENSEARCH_NODE_COUNT_CHECK_ENABLED=false
# OpenSearch index name for storing documents
# Default: documents
# Change this if you want to use a different index name or avoid conflicts.
# Must start with "documents" or "knowledge_filters" — the OpenSearch security
# role (securityconfig/roles.yml) only grants search access to indices
# matching those patterns; any other name causes a 403 AuthorizationException.
OPENSEARCH_INDEX_NAME=documents
# OpenSearch index layout for newly-created OpenRAG indices
# Shard count cannot be changed on an existing index without reindexing.
# Local/dev OpenSearch is single-node, so default to 1 shard / 0 replicas here
# (production deployments default to 2/2 in code; override as needed).
OPENRAG_OPENSEARCH_NUMBER_OF_SHARDS=1
OPENRAG_OPENSEARCH_NUMBER_OF_REPLICAS=0
# Reconcile existing OpenRAG indices' replica counts to
# OPENRAG_OPENSEARCH_NUMBER_OF_REPLICAS on startup. Defaults to true in code
# (for multi-node production); disabled here since local/dev is single-node.
OPENRAG_ENSURE_INDEX_REPLICAS_ON_STARTUP=false
# IBM AMS Authentication (IBM Watsonx Data embedded mode)
# Set IBM_AUTH_ENABLED=true to authenticate via the ibm-openrag-session cookie
# instead of Google OAuth. The raw IBM JWT is also passed directly to OpenSearch.
# When enabled, GOOGLE_OAUTH_CLIENT_ID/SECRET are not required for login.
IBM_AUTH_ENABLED=false
# URL to fetch IBM's JWT public key (used to validate ibm-openrag-session tokens).
IBM_JWT_PUBLIC_KEY_URL=
# Cookie name set by Traefik after successful IBM AMS authentication (default: ibm-openrag-session).
IBM_SESSION_COOKIE_NAME=ibm-openrag-session
# Header injected by Traefik on every forwarded request containing the OpenSearch Basic credentials
# (base64-encoded username:password). Override if your proxy uses a different header name.
IBM_CREDENTIALS_HEADER=X-IBM-LH-Credentials
# Optional: Use these to override authentication for local development/calls when IBM_AUTH_ENABLED=true
IBM_USERNAME=
IBM_PASSWORD=
# Set to true to disable OpenSearch security roles/mapping setup during onboarding/startup
IBM_AUTH_DEV_MODE=false
# make here https://console.cloud.google.com/apis/credentials
GOOGLE_OAUTH_CLIENT_ID=
GOOGLE_OAUTH_CLIENT_SECRET=
# Azure app registration credentials for SharePoint/OneDrive
MICROSOFT_GRAPH_OAUTH_CLIENT_ID=
MICROSOFT_GRAPH_OAUTH_CLIENT_SECRET=
# AWS Access Key ID and Secret Access Key with access to your S3 instance
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
# --- IBM Cloud Object Storage connector (Enterprise/SaaS) ------------------
# Enterprise/SaaS-only bucket connector, gated by IBM_AUTH_ENABLED (like the
# AWS S3 / Azure Blob connectors). Credentials are normally entered per-connection
# in the UI; these env vars are OPTIONAL fallbacks / defaults. Two auth modes are
# supported: IAM (api_key + service_instance_id, default) or HMAC (access key +
# secret, S3-compatible -- works against MinIO for local testing).
IBM_COS_ENDPOINT=
IBM_COS_API_KEY=
IBM_COS_SERVICE_INSTANCE_ID=
IBM_COS_HMAC_ACCESS_KEY_ID=
IBM_COS_HMAC_SECRET_ACCESS_KEY=
#
# Local dev / MinIO testing: set OPENRAG_DEV_IBM_COS=true to enable the
# connector without IBM_AUTH_ENABLED. NEVER use in production.
# OPENRAG_DEV_IBM_COS=false
# Frontend counterpart: also set NEXT_PUBLIC_DEV_IBM_COS=true so the Connectors
# tab and admin Connectors Permission page show IBM COS locally (requires a
# frontend restart to take effect -- Next.js reads NEXT_PUBLIC_* at startup).
# NEXT_PUBLIC_DEV_IBM_COS=false
# --- Azure Blob Storage connector (Enterprise/SaaS) ------------------------
# Enterprise/SaaS-only bucket connector, gated by IBM_AUTH_ENABLED (like the
# AWS S3 / IBM COS connectors). Credentials are normally entered per-connection
# in the UI; these env vars are OPTIONAL fallbacks / defaults for the config
# dialog. Two auth modes are supported: a connection string, OR account name +
# key (+ optional custom blob endpoint).
#
# Feature kill switch for the Azure Blob connector (default: true = enabled).
# Independent of IBM_AUTH_ENABLED: set to false to force-hide the connector in
# the UI even when IBM auth is on. When true, the connector still requires the
# Enterprise/SaaS gate (IBM_AUTH_ENABLED) or OPENRAG_DEV_AZURE_BLOB below --
# this flag is AND-ed with that gate, not an override.
# OPENRAG_AZURE_BLOB_ENABLED=true
#
# Local dev / Azurite testing: set OPENRAG_DEV_AZURE_BLOB=true to enable the
# connector without IBM_AUTH_ENABLED. NEVER use in production.
# OPENRAG_DEV_AZURE_BLOB=false
#
# Connection-string mode (covers real Azure accounts and the Azurite emulator):
# - Real account: copy from Azure Portal -> Storage account -> Access keys
# - Azurite (local dev): AZURE_STORAGE_CONNECTION_STRING="UseDevelopmentStorage=true"
# AZURE_STORAGE_CONNECTION_STRING=
#
# Account-key mode (set account name + key; endpoint optional):
# - Azurite (host-side backend):
# - AZURE_STORAGE_ACCOUNT_NAME=devstoreaccount1
# - AZURE_STORAGE_ACCOUNT_KEY=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==
# - AZURE_STORAGE_ENDPOINT=http://127.0.0.1:10000/devstoreaccount1
# - Azurite (in-compose backend):
# - AZURE_STORAGE_ACCOUNT_NAME=devstoreaccount1
# - AZURE_STORAGE_ACCOUNT_KEY=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==
# - AZURE_STORAGE_ENDPOINT=http://azurite:10000/devstoreaccount1
# AZURE_STORAGE_ACCOUNT_NAME=
# AZURE_STORAGE_ACCOUNT_KEY=
# AZURE_STORAGE_ENDPOINT=
# OPTIONAL: dns routable from google (etc.) to handle continous ingest (something like ngrok works). This enables continous ingestion
WEBHOOK_BASE_URL=
# Model Provider API Keys
OPENAI_API_KEY=
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
# OPTIONAL: Azure OpenAI API version (defaults to LiteLLM default if unset)
# AZURE_OPENAI_API_VERSION=2024-02-01
ANTHROPIC_API_KEY=
OLLAMA_ENDPOINT=
WATSONX_API_KEY=
WATSONX_ENDPOINT=
WATSONX_PROJECT_ID=
# --- IBM watsonx.ai on-prem (Cloud Pak for Data / Software Hub) ----------
# WATSONX_ENDPOINT_ONPREM=https://cpd-cluster.example.com
# WATSONX_USERNAME_ONPREM=
# WATSONX_API_KEY_ONPREM=
# Alternatively provide base64(username:api-key) instead of the two fields above.
# WATSONX_ZEN_API_KEY_ONPREM=
# WATSONX_SPACE_ID_ONPREM=
# WATSONX_PROJECT_ID_ONPREM=
# Provider-scoped TLS policy: false (default), true, or a mounted CA bundle path.
# SSL_VERIFY no longer controls this provider. SSL_CERT_FILE remains available
# as the process trust store when verification is enabled.
# WATSONX_TLS_VERIFY_ONPREM=false
# Tune the ibm-watsonx-ai SDK's native 429 retry used during ingestion embedding.
# OPTIONAL: Max retries = retry attempts (default 10).
# WATSONX_MAX_RETRIES=10
# OPTIONAL: Delay time = base backoff seconds for the jittered exponential backoff (default 0.5).
# WATSONX_DELAY_TIME=0.5
# --- Red Hat OpenShift AI (RHOAI) ------------------------------------------
# Models served by KServe + vLLM inside your own OpenShift cluster, reached over
# the OpenAI-compatible API. vLLM serves ONE model per InferenceService, so chat
# and embeddings are two separate endpoints and both are listed below.
#
# The provider is hidden in every run mode as shipped. To offer it, copy
# src/config/model_providers.yaml, set `rhoai` to true for your run mode, and
# point OPENRAG_MODEL_PROVIDERS_CONFIG (above) at the copy. A backend restart is
# required -- that file is not hot-reloaded.
#
# WARNING: these values are read only while OpenRAG has no stored config yet.
# In the default OPENRAG_STORAGE_MODE=db, provider environment variables (these,
# and OPENAI_API_KEY / WATSONX_* / AZURE_OPENAI_* alike) are applied exactly
# once, when the database is first populated on the first boot; after that the
# stored config is authoritative and the environment is not consulted again.
# In files/hybrid mode the same happens the first time anyone saves in the
# Settings UI (config.edited becomes true). Either way: seed BEFORE the first
# boot, and afterwards change the provider through Settings, not the environment.
#
# Chat endpoint -- the predictor Service of your chat InferenceService, ending
# in /v1. In-cluster:
# https://openrag-chat-predictor.openrag-models.svc.cluster.local:8443/v1
# RHOAI_ENDPOINT=
#
# Embeddings endpoint -- a second InferenceService. Leave unset only if a single
# endpoint serves both. In-cluster:
# https://openrag-embed-predictor.openrag-models.svc.cluster.local:8443/v1
# RHOAI_EMBEDDINGS_ENDPOINT=
#
# Kubernetes bearer token used for BOTH endpoints. Its subject needs `get` on
# inferenceservices in the model namespace:
# oc create token openrag-inference -n openrag --duration=8760h
# Put the real value in a Secret, never in a committed file.
# RHOAI_API_KEY=
#
# TLS trust for the endpoints' certificates. An in-cluster Service is signed by
# OpenShift's service-serving CA, which OpenShift projects into every pod:
# RHOAI_TLS_VERIFY=/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt
# Unlike SSL_CERT_FILE this is scoped to this provider only, so it cannot break
# OpenAI or Anthropic in the same deployment.
# Set to `false` to skip verification. That is for ONE case -- an oc port-forward
# to localhost, whose certificate cannot match -- and must never be set on a
# deployed environment.
# RHOAI_TLS_VERIFY=
#
# Maximum embedding requests OpenRAG sends to the embeddings endpoint at once
# (default 16, sized for a GPU-served model; 0 = no limit). Extra requests wait
# inside OpenRAG. A CPU-served model copes with 16 when its InferenceService
# sets CPU requests = limits and VLLM_CPU_OMP_THREADS_BIND to that many cores
# (e.g. 6 and 0-5); otherwise vLLM binds a thread per node core and the pod is
# throttled to well under one chunk per second. Set 4 for such a slow endpoint:
# the endpoint's kube-rbac-proxy answers 502 once a request waits upstream past
# its 30s timeout -- which fails folder uploads (several files x 8 embedding
# threads). Also editable in Settings. One of these
# slots is reserved for search and chat queries, so they are not queued behind
# ingestion (with a limit of 1, both share the single slot).
# RHOAI_EMBEDDING_MAX_CONCURRENCY=
#
# Selecting the models. The ids are each InferenceService's --served-model-name,
# not an image tag. OpenRAG lists the real ones from each endpoint's /v1/models.
# LLM_PROVIDER=rhoai
# LLM_MODEL=granite-3.3-2b-instruct
# EMBEDDING_PROVIDER=rhoai
# EMBEDDING_MODEL=granite-embedding-english-r2
#
# NOTE: the chat InferenceService must be started with --enable-auto-tool-choice
# and a --tool-call-parser (e.g. granite). OpenRAG's agent is tool-calling
# driven, and without them vLLM rejects every tool call with a 400.
# LLM Provider configuration. Providers can be "anthropic", "watsonx", "ibm" or "ollama".
LLM_PROVIDER=
LLM_MODEL=
# OPTIONAL: Custom system prompt for the chat agent. Overrides the default prompt baked into the Langflow flow.
# SYSTEM_PROMPT=
# Embedding provider configuration. Providers can be "watsonx", "ibm" or "ollama".
EMBEDDING_PROVIDER=
EMBEDDING_MODEL=
# Optional JSON map for vectors indexed before embedding_provider was stored.
# text-embedding-3-small is inferred as OpenAI automatically.
OPENRAG_LEGACY_EMBEDDING_PROVIDER_MAP={}
# Knowledge ingestion tuning
# OPTIONAL: Document chunk size in tokens (default configured in Langflow flow)
# CHUNK_SIZE=
# OPTIONAL: Overlap between chunks in tokens (default configured in Langflow flow)
# CHUNK_OVERLAP=
# OPTIONAL: Enable OCR for scanned PDFs and images (default: false)
# OCR_ENABLED=false
# OPTIONAL: Generate text descriptions for images found in documents (default: false)
# PICTURE_DESCRIPTIONS_ENABLED=false
# Port Configuration
# Change these values if you have port conflicts with other services on your system
# Default ports: Frontend=3000, Langflow=7860
FRONTEND_PORT=3000
LANGFLOW_PORT=7860
# Internal URL the OpenRAG backend uses to communicate with Langflow.
# When running via docker-compose this is set automatically to http://langflow:7860.
# Override only when running the backend outside Docker or pointing at a remote Langflow instance.
# LANGFLOW_URL=http://localhost:7860
# OPTIONAL url for openrag link to langflow in the UI
# If you change LANGFLOW_PORT, also update LANGFLOW_PUBLIC_URL to match the new port (e.g., http://localhost:7861)
LANGFLOW_PUBLIC_URL=
# OPTIONAL: Override the full docling-serve URL (e.g., for remote instances)
# If not set, auto-detects host and uses port 5001
# DOCLING_SERVE_URL=http://my-docling-server:5001
# DOCLING_SERVE_VERIFY_SSL=true
# OPTIONAL: OCR engine used by docling for scanned documents. Options: "easyocr" (default), "tesseract", "tesseract_cli"
# DOCLING_OCR_ENGINE=easyocr
# OPTIONAL: Override host for docling service (for special networking setups)
# HOST_DOCKER_INTERNAL=host.containers.internal
# Langflow auth
LANGFLOW_AUTO_LOGIN=False
LANGFLOW_SUPERUSER=
LANGFLOW_SUPERUSER_PASSWORD=
LANGFLOW_NEW_USER_IS_ACTIVE=False
LANGFLOW_ENABLE_SUPERUSER_CLI=False
# Disable custom component creation in Langflow
LANGFLOW_ALLOW_CUSTOM_COMPONENTS=false
# ─────────────────────────────────────────────────────────────────────────────
# Langflow Container Variables
# These variables are passed directly to the Langflow container by docker-compose.
# They are NOT read by the OpenRAG Python backend.
# ─────────────────────────────────────────────────────────────────────────────
# Langfuse tracing (optional)
# Get keys from https://cloud.langfuse.com or your self-hosted instance
# Exception to the note above: the backend also reads these when
# OPENRAG_TRACING_ENABLED=true (below), so both trace to the same project.
LANGFUSE_SECRET_KEY=
LANGFUSE_PUBLIC_KEY=
# Langfuse URL, as shown in Langfuse's setup steps: https://cloud.langfuse.com (EU),
# https://us.cloud.langfuse.com (US), or your self-hosted instance (e.g., http://localhost:3002).
# Self hosting outside of the docker network: LANGFUSE_BASE_URL=http://host.docker.internal:3000
# Langflow needs it set to trace. LANGFUSE_HOST is still accepted as an older name.
LANGFUSE_BASE_URL=
# Backend tracing to Langfuse (optional, default off). Traces every model call
# the backend makes through its LLM gateway — embeddings and chat, all
# providers — with model, provider, latency, token usage, cost and errors.
# Requires the LANGFUSE_* keys above and the `tracing` extra (`uv sync --extra
# tracing`; included in the published backend image).
OPENRAG_TRACING_ENABLED=false
# Traces carry metadata only by default. Set to true to also record prompts,
# completions and embedding inputs (document text).
OPENRAG_TRACING_CAPTURE_CONTENT=false
# In OPENRAG_RUN_MODE=saas, content capture additionally requires this.
OPENRAG_TRACING_ALLOW_CONTENT_IN_SAAS=false
# OPENRAG_LLM_TOKEN is seeded to the non-empty string "None" in Langflow
# (docker-compose OPENRAG_LLM_TOKEN=None). Langflow treats an empty Credential
# as missing. OpenRAG overwrites the value with a hop token per run.
# OPTIONAL: A development-mode only configuration value that allows additional origins (domains/hosts) to make requests to the Next.js dev server (next dev).
# - A list of comma-separate hostnames may be specified
# - e.g. 9.46.110.49,10.21.103.227,openrag.example.com
NEXT_ALLOWED_DEV_ORIGINS=
# OPTIONAL: Number of worker processes for concurrent request handling
# - Increase for higher throughput; but, factor in CPU / memory constraints
# MAX_WORKERS=4 # Backend ingestion workers (default: min(4, CPU_COUNT // 2))
# LANGFLOW_WORKERS=2 # Langflow workers (default: 1)
# DOCLING_WORKERS=2 # Docling workers (default: 1)
# Logging and Service
# Format for log messages (default: json)
LOG_FORMAT=
# OPTIONAL: Set the logging level for the Backend service
# - Supported values: DEBUG, INFO, WARNING, ERROR, CRITICAL
# - Default: INFO
# LOG_LEVEL=DEBUG
# OPTIONAL: Set the logging level for the Langflow container
# - Supported values: DEBUG, INFO, WARNING, ERROR, CRITICAL
# - Default: INFO
# - DEBUG logs every component's full result, including whole parsed Docling
# documents (multi-MB lines). Writing them blocks Langflow's single worker
# during ingestion, so health checks time out. Enable only when debugging a flow.
# LANGFLOW_LOG_LEVEL=DEBUG
# OPTIONAL: Disable colored log output (https://no-color.org)
# - When set (to any value), ANSI color codes are omitted from log output
# NO_COLOR=1
# OPTIONAL: Enable or disable HTTP access logging events
# - e.g. INFO: 127.0.0.1:45132 - "GET /tasks HTTP/1.1" 200 OK
# - Default: true
# ACCESS_LOG=false
# OpenRAG Configuration
# The version tag for OpenRAG Docker images (e.g., 'latest', 'v1.0.0').
# This is automatically managed by the TUI during updates to match the Python package version,
# but can be pinned here to lock the deployment to a specific version when running OpenRAG with Make commands.
OPENRAG_VERSION=latest
# Container image and registry configuration.
# By default OpenRAG pulls its images from Docker Hub (docker.io/langflowai).
# Set these to pull from a private registry or internal mirror instead, e.g. in
# an enterprise or air-gapped environment. Mirror the images first — see
# https://docs.openr.ag/docker#private-registry
#
# Registry host for the OpenRAG-owned images (openrag-backend, openrag-frontend,
# openrag-langflow, openrag-opensearch). Hostname only: no scheme, no trailing
# slash. Include the port if non-standard, e.g. registry.example.com:5000.
# Note: setting this to anything other than docker.io disables the TUI's
# Docker Hub update check (no upgrade or up-to-date notification is shown).
# Default: docker.io
# IMAGE_REGISTRY=registry.example.com
# Organization / namespace holding the OpenRAG-owned images within
# IMAGE_REGISTRY. Images resolve to IMAGE_REGISTRY/IMAGE_ORG/<image>:<tag>.
# Default: langflowai
# IMAGE_ORG=platform-team
# Overrides the tag for all OpenRAG-owned images. Takes precedence over
# OPENRAG_VERSION above; falls back to OPENRAG_VERSION, then 'latest'.
# Use this when your mirror re-tags images differently from OpenRAG releases.
# Default: unset
# OPENRAG_IMAGE_TAG=0.6.4
# Registry host for the OpenSearch Dashboards image only, so you can mirror it
# without redirecting the OpenRAG-owned images. The repository path and tag are
# fixed, so the mirrored image must exist at
# <DASHBOARDS_REGISTRY>/opensearchproject/opensearch-dashboards:3.6.0
# Default: docker.io
# DASHBOARDS_REGISTRY=registry.example.com
# Docker Compose project name. Change this to run multiple instances of OpenRAG alongside each other.
COMPOSE_PROJECT_NAME=openrag
# Path configuration (override defaults for custom directory layouts)
# OPENRAG_DATA_PATH=./data
# OPENRAG_KEYS_PATH=./keys
# OPENRAG_CONFIG_PATH=./config
# OPENRAG_FLOWS_PATH=./flows
# OPENRAG_FLOWS_BACKUP_PATH= # defaults to <OPENRAG_FLOWS_PATH>/backup
# Comma-separated list of host directories the TUI watches for documents to ingest.
# The TUI derives OPENRAG_DOCUMENTS_PATH (below) from the first entry for Docker's volume mount.
# OPENRAG_DOCUMENTS_PATHS=$HOME/.openrag/documents
#
# Single directory path mounted into the OpenRAG container by docker-compose.
# Set automatically by the TUI from OPENRAG_DOCUMENTS_PATHS; override only if running without the TUI.
# OPENRAG_DOCUMENTS_PATH=./openrag-documents
# Langflow Configuration
# API Key for authenticating with Langflow.
# If not provided, OpenRAG will automatically generate one using the superuser credentials
# (LANGFLOW_SUPERUSER and LANGFLOW_SUPERUSER_PASSWORD).
LANGFLOW_KEY=
# Number of retry attempts when generating the Langflow API key (default: 15)
LANGFLOW_KEY_RETRIES=
# Delay in seconds between API key generation retry attempts (default: 2.0)
LANGFLOW_KEY_RETRY_DELAY=
# Version of Langflow (informational/future use)
# LANGFLOW_VERSION=
# Service name used in logs (default: openrag)
SERVICE_NAME=openrag
# Secret key for session management (auto-generated if not provided)
SESSION_SECRET=
# --- Instana APM -----------------------------------------------------------
# Enable auto-instrumentation via Instana's Python tracer.
# Requires a local Instana host agent (see `make instana-agent-up`).
# The tracer ships as the optional `apm` extra, so a host-run backend
# (`make backend`) needs `uv sync --extra apm` once; the backend container
# image already includes it. Without the package the backend logs a warning
# and runs untraced rather than failing to start.
# - Default: false
# INSTANA_ENABLED=true
#
# OPTIONAL: Local Instana agent host.
# The host agent (`make instana-agent-up`) uses host networking and publishes
# 42699 on the host's loopback, so the correct value depends on where the
# backend process runs:
# - `make backend` (backend on the host) → 127.0.0.1
# - `make dev` / `make dev-cpu` (in Docker) → host.docker.internal
# Leave unset to accept the per-topology default: docker-compose defaults the
# backend container to host.docker.internal; the tracer's own built-in default
# is `localhost`, which is what a host-run backend gets.
# INSTANA_AGENT_HOST=127.0.0.1
# OPTIONAL: Local Instana agent port
# - Default: 42699
# INSTANA_AGENT_PORT=42699
#
# OPTIONAL: Service name shown in Instana's Analyze Traces / Applications view.
# INSTANA_SERVICE_NAME="OpenRAG Backend"
#
# OPTIONAL: Custom zone the host/process is grouped under in the
# Infrastructure view. The process entry itself is named by the host agent from
# the process command line, not by the tracer.
# INSTANA_ZONE="openrag-dev"
#
# OPTIONAL: Instana tracer's own log verbosity
# - Default: info
# INSTANA_LOG_LEVEL=info
#
# Span categories/types the tracer must not trace. Comma-separated; `true`
# disables every category.
# - Tracer default: <empty> (everything traced)
# - Set here to `logging`, deliberately, and left uncommented so a fresh .env
# carries it.
#
# WHY: with logging spans on, every WARNING/ERROR logged inside an active
# request trace appends an Event to a list shared by ALL spans (the mutable
# default of InstanaSpan.__init__ in instana 3.17.0), which is never freed, and
# each new log span re-walks the whole list. That is an unbounded memory leak
# and O(n^2) CPU on a long-running backend: measured here at 10.9us -> 1010us
# per in-trace warning, still climbing after 2000 of them. `logging` brings it
# back to 26us and holds flat. src/ has ~750 warning/error call sites, many on
# request paths.
#
INSTANA_TRACING_DISABLE=logging
#
# When the tracer captures a Python stack trace for EXIT spans.
# Accepted: all | error | none (anything else logs a warning and falls back to
# `all`, so never leave this set to an empty string).
# - Tracer default: all
# - Set here to `error`, and left uncommented for the same reason as above.
#
# WHY: EXIT_SPANS covers httpx, urllib3 (OpenSearch), sqlalchemy, aiohttp-client
# and boto3, so `all` means a full traceback.extract_stack() — with linecache
# source reads — on every outbound HTTP call, every SQL query and every
# retrieval. Measured 127us at stack depth 30, 221us at 60, 355us at 100; a
# uvicorn/starlette/async route stack is deep and a chat request makes 10-30
# exit spans. `error` keeps the stack where it is actually diagnostic (errored
# spans) and drops it from the happy path.
INSTANA_STACK_TRACE=error
#
# OPTIONAL: Maximum frames kept per captured stack trace (1-40).
# - Default: 30
# INSTANA_STACK_TRACE_LENGTH=30
#
# Query-string parameters the tracer redacts before spans leave the host.
# Format: <matcher>:<name>[,<name>], matcher one of equals, equals-ignore-case,
# contains, contains-ignore-case, regex.
# - Tracer default: contains-ignore-case:key,pass,secret
# - Set here to a regex that keeps that credential coverage and adds
# OpenRAG's free-text query parameters, deliberately, and left uncommented
# so a fresh .env carries it.
#
# WHY: the tracer default only catches credential-shaped names. It does NOT
# redact free-text values, so GET /v2/files/search?q=<user query> is exported
# to Instana verbatim, along with the `search` and `filename` parameters used
# by file listing. Spans never carry request or response bodies, so chat
# prompts and document text stay local regardless of this setting.
#
# Set this to an empty value (not commented out) to fall back to the tracer's
# own weaker default; it logs a "Couldn't parse INSTANA_SECRETS" warning each
# time you do.
#
# NOTE: uses `\Z` rather than a trailing `$` to anchor exact names. The
# tracer matches with Python's re.match(), which already anchors at the
# start of the string, so a leading `^` would be redundant and a trailing
# `$` is the only anchor doing real work here. This Makefile includes and
# exports every `.env` line as GNU Make syntax (see Makefile's ENV_FILE
# loading), which treats a bare `$` as a Make variable reference — `$,`
# silently resolves to an undefined variable and eats both the `$` and the
# following comma. Reintroducing `$` here will silently break this
# redaction under `make backend` / `make dev` without any warning.
INSTANA_SECRETS=regex:.*key.*,.*pass.*,.*secret.*,.*token.*,q\Z,search\Z,filename\Z
#
# Instana host agent key.
# Both this and the endpoint below come from your own tenant's
# Infrastructure > Add a Host wizard.
# WARNING: setting these enables `make instana-agent-up`, which starts a
# privileged container in the host PID namespace with Docker socket access.
# Local development only - do not run it on a shared or production host.
# INSTANA_AGENT_KEY=
# OPTIONAL: Instana host agent endpoint.
# The ingress is region-specific — the default below is only one of several,
# so take the value your tenant's Add a Host wizard shows you.
# - Default: ingress-coral-saas.instana.io
# INSTANA_AGENT_ENDPOINT=ingress-coral-saas.instana.io
# OPTIONAL: Instana host agent port
# - Default: 443
# INSTANA_AGENT_ENDPOINT_PORT=443
# OPTIONAL: Instana host agent image tag.
# Pinned in docker-compose.yml because the agent runs privileged with host PID
# and Docker socket access. Set this to try a newer agent without editing
# compose; see https://icr.io/v2/instana/agent/tags/list for available tags.
# - Default: 1.323.1
# INSTANA_AGENT_IMAGE_TAG=1.323.1
# OPTIONAL: JWT signing key for token issuance and verification.
# If not set, OpenRAG generates an RSA key pair (private_key.pem / public_key.pem)
# under OPENRAG_KEYS_PATH at startup and uses RS256 signing.
# Accepted values:
# - RSA private key in PEM format (PKCS#8 or PKCS#1) → RS256
# - Plain string → HS256 (symmetric; JWKS endpoint returns an empty key set)
# When set, the on-disk key files are never read or created.
#
# PEM keys must be set as a double-quoted single-line value with literal \n
# separators. python-dotenv expands \n in double-quoted strings to real newlines,
# which is required by the PEM parser. Multiline values break Make's .env parsing,
# and single-quoted or unquoted values do not expand \n.
#
# Generate and format a test key with:
# openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 2>/dev/null \
# | awk '{printf "%s\\n", $0}' | sed 's/^/"/' | sed 's/$/"/'
#
# JWT_SIGNING_KEY=
# OPTIONAL: The OpenRAG application execution mode or deployment target.
# - Used to configure the operation of the application based on it's execution context.
# Values:
# - "oss": Open Source Software (default)
# - "saas": Public Cloud
# - "on_prem": Private Cloud
OPENRAG_RUN_MODE=oss
# OPTIONAL: Path to a YAML file listing which model providers are visible in
# each run mode above. Defaults to the shipped src/config/model_providers.yaml,
# which is what Settings, Onboarding and the model pickers all read. Set this
# only to override the shipped list for a deployment; an unreadable file falls
# back to the shipped one.
# OPENRAG_MODEL_PROVIDERS_CONFIG=
# Feature flag for the preview-mode ingest backend (default: false = disabled).
# When true, the frontend can request preview ingests that show progress and a
# live index proof without persisting Docling layout JSON. AND-ed with the run
# mode: preview is only ever available in the "oss" and "saas" run modes above.
# OPENRAG_INGEST_PREVIEW_ENABLED=false
# Feature flag for workspace-level OAuth connector credential overrides
# (default: false = disabled). When true, admins can override the
# env-var-configured OAuth client id/secret per connector from Connector
# Settings, and run a Test Connection check. When false, connectors only
# ever use their env var credentials and the admin UI/API for overrides is
# hidden/disabled.
# OPENRAG_WORKSPACE_OAUTH_OVERRIDES_ENABLED=false
# Feature flag for the managed public-website connector (default: false =
# disabled). When true, users can add website sources from Knowledge and the
# Connectors settings page. This is also enforced by the backend URL APIs.
# OPENRAG_URL_CONNECTOR_ENABLED=false
# Permission/identity cache backend. Only "memory" is currently wired.
# When CACHE_BACKEND=memory the RBAC permission cache and OAuth-subject
# cache are per-process, so OpenRAG must run with UVICORN_WORKERS=1 (and
# replicaCount=1 in helm). Anything >1 hard-fails at startup until cache
# is shared across processes (planned: Redis).
CACHE_BACKEND=memory
# UVICORN_WORKERS=1
# Storage mode. Default `db` — workspace config + chat history live in
# the SQL DB only; no `config.yaml`, `conversations.json`, or
# `session_ownership.json` are ever written. Pre-existing JSON files
# are imported once on first boot, then ignored.
# - db (default) DB-only, no JSON written
# - hybrid DB + JSON dual-write (Phase B fallback)
# - files legacy JSON-only path; DB untouched
OPENRAG_STORAGE_MODE=db
# TLS verification when OpenRAG fetches JWT signing keys from the token iss URL
# (gateway-forwarded JWT / RBAC role sync). Default false (internal issuers).
# Set true when the issuer uses a cert trusted by the pod CA bundle.
# OPENRAG_JWT_ISSUER_VERIFY_TLS=true
# Verify forwarded JWT signatures via iss JWKS (default false).
# Set true when OpenRAG must verify signatures (no trusted upstream auth).
# OPENRAG_JWT_VERIFY_SIGNATURE=true
# RBAC kill switch. Default OFF — the system behaves like the pre-RBAC
# release: any authenticated user has full access; API-key role
# overrides are also bypassed. Set to `true` to turn the permissions
# system on for multi-user deployments. Available in all run modes.
# OPENRAG_RBAC_ENFORCE=true
# Default role for new users (JWT role sync off). Does not change existing
# users unless OPENRAG_SYNC_DEFAULT_ROLE is also enabled.
# OPENRAG_DEFAULT_ROLE=user
# OPENRAG_NOAUTH_ROLE=admin
# Dev-only (OSS run mode): run scripts/sync_default_user_roles.py manually
# to migrate users when OPENRAG_DEFAULT_ROLE changes. Ignored in saas/on_prem.
# OPENRAG_SYNC_DEFAULT_ROLE=false