Skip to content
NodeKAT Documentation

Installation

Prerequisites

Section titled “Prerequisites”
  • Docker Engine 20.10+ and Docker Compose 2.0+
  • A running FalkorDB instance (external)
  • At least one LLM API key (e.g., OpenAI)
  • 4 GB+ available RAM

See Prerequisites for detailed requirements.

Step 1: Clone the Repository

Section titled “Step 1: Clone the Repository”
Terminal window
git clone https://github.com/nodekat/FluidRAG.git
cd FluidRAG

Step 2: Configure Environment

Section titled “Step 2: Configure Environment”
Terminal window
cp .env.example .env

Edit .env and set the required values. At minimum, configure:

Terminal window
# FalkorDB — your external instance
FALKORDB_HOST=10.0.70.120
FALKORDB_PORT=6397
KG_NAME=your_kg_name


# Optional: FalkorDB password (if auth is enabled)
# FALKORDB_PASSWORD=

The defaults for etcd, Redis, and API settings work out of the box for a local deployment. See the Configuration page for all available options.

Step 3: Build Images

Section titled “Step 3: Build Images”

Build all four Docker images:

Terminal window
make build-all-local VERSION=0.4.1

This builds:

ImageBuilt FromSize
fluidrag:0.4.1Dockerfile (Python 3.12, multi-stage)~800 MB
fluidrag-admin-api:0.4.1services/config-api/Dockerfile~400 MB
fluidrag-admin-ui:0.4.1services/admin-ui/Dockerfile~50 MB
fluidrag-gateway:0.4.1services/gateway/Dockerfile (nginx)~50 MB

First build takes 5–10 minutes. Subsequent builds use layer caching (3–5 min).

Step 4: Start Services

Section titled “Step 4: Start Services”
Terminal window
docker-compose up -d

The startup sequence follows dependency order:

  1. etcd initializes and passes health check
  2. etcd-bootstrap runs once — populates ~60 config keys and 30 secret placeholders into etcd, then exits
  3. Redis starts and passes health check
  4. RQ workers (2), scheduler, and dashboard connect to Redis
  5. API server connects to Redis and etcd, then begins serving on port 8000
  6. Config API and Admin UI start
  7. Gateway (nginx) starts routing traffic on port 80

Step 5: Verify Deployment

Section titled “Step 5: Verify Deployment”

Check Container Status

Section titled “Check Container Status”
Terminal window
docker-compose ps

You should see 11 containers — 10 running and etcd-bootstrap with status Exited (0) (it ran successfully).

Health Check

Section titled “Health Check”
Terminal window
curl http://localhost:8000/health

A successful response returns JSON with component statuses:

{
  "status": "healthy",
  "falkordb": "connected",
  "rag": "available"
}

Check etcd Bootstrap

Section titled “Check etcd Bootstrap”
Terminal window
docker logs etcd-bootstrap

Look for Bootstrap completed successfully in the output. If it failed, see Troubleshooting.

Step 6: First-Time Admin UI Setup

Section titled “Step 6: First-Time Admin UI Setup”
  1. Open http://localhost/config-ui in your browser
  2. Navigate to Settings → Secrets
  3. Add your API keys (at minimum OPENAI_API_KEY)
  4. Navigate to Settings → LLM to verify provider and model settings
  5. Check Health page to confirm all components are connected

Changes take effect immediately — no container restart needed.

Next Steps

Section titled “Next Steps”