Configuration

FluidRAG uses a two-layer configuration system:

1. .env file — Infrastructure connectivity (Docker Compose reads these at container start). Requires a restart to change.
2. etcd — Runtime configuration (LLM models, API keys, feature flags, search tuning). Managed via Admin UI with hot-reload — no restart.

Environment Variables

These are set in your .env file at the project root. See .env.example for the full annotated reference.

etcd (Configuration Store)

Variable	Default	Description
USE_ETCD	true	Enable etcd-based configuration
ETCD_HOST	etcd	etcd container hostname
ETCD_PORT	2379	etcd client port
ETCD_CONFIG_PREFIX	/config	Key prefix for configuration
ETCD_SECRETS_PREFIX	/secrets	Key prefix for secrets

FalkorDB (External)

Variable	Default	Description
FALKORDB_HOST	localhost	Your FalkorDB instance host
FALKORDB_PORT	6379	Your FalkorDB instance port
FALKORDB_PASSWORD	—	Managed as etcd secret; set here only if needed before etcd bootstrap
KG_NAME	DEFAULT_KG_v1	Knowledge graph name in FalkorDB

Redis (Bundled)

Variable	Default	Description
REDIS_HOST	redis	Redis container hostname
REDIS_PORT	6379	Redis port
REDIS_PASSWORD	redis123	Redis auth; managed as etcd secret in production
REDIS_DB	0	Redis database number

API Server

Variable	Default	Description
API_HOST	0.0.0.0	Bind address
API_PORT	8000	API server port
LOG_LEVEL	INFO	Logging verbosity
SERVICE_VERSION	0.4.1	Reported in health endpoint

Admin UI & OAuth

Variable	Default	Description
FRONTEND_URL	http://localhost/config-ui/	Admin UI URL (used for OAuth redirects)
CORS_ORIGINS	http://localhost,...	Allowed CORS origins (comma-separated)
ADMIN_ALLOWED_EMAILS	—	Email allowlist for Admin UI login
SECRET_KEY	change-me-...	Session secret (generate with python -c "import secrets; print(secrets.token_hex(32))")

Gateway (Nginx)

Variable	Default	Description
NGINX_ENABLE_SSL	false	Enable HTTPS mode
NGINX_SERVER_NAME	_	Server name (use your domain for SSL)
SSL_CERT_PATH	—	Host path to SSL certificate (required when SSL enabled)
SSL_KEY_PATH	—	Host path to SSL key (required when SSL enabled)

When SSL is enabled, the gateway runs two HTTP server blocks — one for internal Docker traffic (no redirect) and one that redirects external traffic to HTTPS.

etcd-Managed Configuration

These settings are configured through the Admin UI at http://localhost/config-ui and stored in etcd. Changes take effect immediately via hot-reload.

LLM Providers

Each pipeline layer can use a different provider and model:

Setting	Description	Example
llm.logic_layer_provider	Agent execution provider	openai, anthropic, google
llm.logic_layer_model	Agent execution model	gpt-4o-mini, gemini-2.5-flash-latest
llm.route_layer_provider	Query classification provider	openai
llm.synthesis_layer_provider	Response generation provider	openai
llm.entity_extraction_provider	Ingestion pipeline provider	openai
llm.embedding_provider	Embedding provider	openai, google, cohere, voyageai
llm.embedding_model	Embedding model	text-embedding-3-large
llm.embedding_dimensions	Vector dimensions	3072 (hot-reload supported)

Supported providers: OpenAI, Anthropic, Google, AWS Bedrock, Groq, OpenRouter, DeepSeek, Fireworks, OpenAI-Compatible.

Feature Flags

Flag	Default	Description
features.sourcebot_enabled	false	Enable code search (Sourcebot/Zoekt)
features.mcp_enabled	false	Enable MCP endpoint
features.enable_multi_instance_tracking	true	Multi-instance file tracking
features.classify_llm_fallback	—	LLM fallback for query classification
features.classify_default_action	—	Default classification behavior

Search & RAG

Setting	Default	Description
search.strategy	graph_dense	Search strategy: graph_only, dense_only, graph_dense, code_only, graph_dense_code
search.fusion_weight_graph	0.4	Graph score weight in fusion
search.fusion_weight_dense	0.6	Dense score weight in fusion
search.fusion_multimodal_bonus	1.1	Bonus for results found in both graph and dense

Chunking

Setting	Default	Description
chunking.strategy	semantic_llamaindex	Chunking strategy
chunking.pre_segmentation_threshold	32000	Token threshold for pre-segmenting large docs

Secrets

All API keys and credentials are stored under /secrets/ in etcd:

Key	Description
/secrets/OPENAI_API_KEY	OpenAI API key
/secrets/FALKORDB_PASSWORD	FalkorDB auth password
/secrets/SLACK_BOT_TOKEN	Slack bot token (xoxb-...)
/secrets/SLACK_USER_TOKEN	Slack user token (xoxp-...)
/secrets/JIRA_CLIENT_ID	Jira OAuth client ID
/secrets/JIRA_CLIENT_SECRET	Jira OAuth client secret
/secrets/GITHUB_TOKEN	GitHub PAT

Configure these through the Admin UI Settings → Secrets tab. Never commit secrets to .env or version control.

Volume Mounts

The following directories are mounted from the host into containers:

Host Path	Container Path	Purpose
./data	/app/data	Application data
./logs	/app/logs	Log files
./ingestion_data	/app/ingestion_data	Ingested document storage
./extraction_data	/app/extraction_data	Extracted source data
./config/ontologies	/app/config/ontologies	Ontology files (read-write for generated ontologies)

Persistent Volumes

Docker-managed volumes survive container recreation:

Volume	Used By	Purpose
etcd_data	etcd	Configuration store data
redis_data	Redis	Job queue state, AOF persistence

Gateway Routes

The nginx gateway routes traffic based on URL path:

Path	Upstream	Description
/config-ui/	admin-ui:80	Admin dashboard
/config-api/	config-api:8001	Admin backend API
/backend-api/	api:8000	FluidRAG backend API
/mcp/	api:8000/mcp/	MCP endpoint (long-lived connections)
/jobqueue/	rq-dashboard:9181	RQ Dashboard (via host.docker.internal)
/	host.docker.internal:3080	FluidLibreUI chat (catch-all)