Quick Start

Step 1: Clone the Repository

git clone https://github.com/nodekat/FluidRAG.git
cd FluidRAG

Step 2: Configure Environment Variables

Copy the example environment file and edit it:

cp .env.example .env

Open .env and configure the required settings:

# etcd (configuration store — required)
USE_ETCD=true
ETCD_HOST=etcd
ETCD_PORT=2379

# FalkorDB (your external instance)
FALKORDB_HOST=10.0.70.120    # Your FalkorDB host
FALKORDB_PORT=6397            # Your FalkorDB port
KG_NAME=your_kg_name          # Knowledge graph name

# Redis (bundled — defaults are fine for local)
REDIS_HOST=redis
REDIS_PORT=6379

# Application
LOG_LEVEL=INFO

The .env.example file is thoroughly commented — read through it to understand all available options. Most configuration (LLM models, feature flags, search tuning) is managed through etcd and the Admin UI after deployment.

Step 3: Build Docker Images

FluidRAG uses four Docker images. Build them all with:

make build-all-local VERSION=0.4.1

This builds:

Image	Purpose
fluidrag:0.4.1	API server + RQ workers (Python)
fluidrag-admin-api:0.4.1	Admin configuration backend
fluidrag-admin-ui:0.4.1	Admin dashboard (React)
fluidrag-gateway:0.4.1	Nginx reverse proxy

The first build takes 5–10 minutes. Subsequent builds use Docker layer caching and complete in 3–5 minutes.

Tip

If you change pyproject.toml dependencies, run make uv-lock before building to regenerate the lockfile.

Step 4: Start Services

docker-compose up -d

Services start in dependency order:

1. etcd starts and passes its health check
2. etcd-bootstrap runs once to populate default configuration (~60 keys, 30 secret placeholders)
3. Redis starts and passes its health check
4. RQ workers (2), RQ scheduler, RQ dashboard connect to Redis
5. API server connects to Redis and etcd
6. Config API and Admin UI start
7. Gateway (nginx) starts routing traffic

Step 5: Verify

Check that all containers are running:

docker-compose ps

You should see 11 containers with status Up. Verify the API is healthy:

curl http://localhost:8000/health

A successful response includes component statuses for FalkorDB, OpenAI, and RAG availability.

Next Step

Now that FluidRAG is running, configure your API keys and send your first query:

Your First Query →