Docker Deployment

FluidRAG runs as a set of Docker containers managed by Docker Compose. The stack includes an API server, background workers, a configuration store, and an admin dashboard — all connected through an nginx gateway.

Overview

11 Services

etcd, Redis, API, 2 RQ workers, scheduler, dashboard, config API, admin UI, gateway, and a one-time bootstrap job.

Hot-Reload Config

All runtime configuration (LLM models, feature flags, search tuning) lives in etcd. Changes via Admin UI take effect instantly.

Scalable Workers

Two RQ workers handle ingestion, extraction, and ontology jobs. Add more by duplicating the worker service.

Multi-Platform Builds

Docker Bake builds for native (dev) or linux/amd64 (prod). Images publish to GitHub Container Registry.

Architecture

                    ┌─────────────┐
                    │   Gateway   │ :80/:443 (nginx)
                    └──────┬──────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
     /config-ui/    /config-api/    /backend-api/
            │              │              │
     ┌──────┴──────┐ ┌────┴────┐  ┌──────┴──────┐
     │  Admin UI   │ │Config API│  │  API Server │ :8000
     └─────────────┘ └────┬────┘  └──────┬──────┘
                           │              │
                    ┌──────┴──────────────┴──────┐
                    │                             │
              ┌─────┴─────┐               ┌──────┴──────┐
              │   etcd    │ :2379         │    Redis    │ :6379
              │ (config)  │               │  (queues)   │
              └───────────┘               └──────┬──────┘
                                                  │
                                          ┌───────┼───────┐
                                          │       │       │
                                     Worker 1  Worker 2  Scheduler

The API server also connects to your external FalkorDB instance (not shown) for knowledge graph operations.

Services

Service	Image	Port	Purpose
etcd	coreos/etcd:v3.6.8	2379, 2380	Configuration store (source of truth)
etcd-bootstrap	fluidrag:0.4.1	—	One-time etcd initialization (exits after)
redis	redis:7-alpine	6379	Job queue, caching, session storage
api	fluidrag:0.4.1	8000	FastAPI backend (OpenAI-compatible API)
rq-worker-1	fluidrag:0.4.1	—	Background job processor
rq-worker-2	fluidrag:0.4.1	—	Background job processor
rq-scheduler	fluidrag:0.4.1	—	Scheduled job enqueuer (60s interval)
rq-dashboard	fluidrag:0.4.1	9181	Job monitoring UI
config-api	fluidrag-admin-api:0.4.1	—	Admin backend (settings, secrets, prompts)
admin-ui	fluidrag-admin-ui:0.4.1	—	Admin dashboard (React)
gateway	fluidrag-gateway:0.4.1	80, 443	Nginx reverse proxy

Documentation

Topic	Description
Installation	Step-by-step guide to deploy FluidRAG with Docker Compose
Configuration	Environment variables, etcd-managed settings, volume mounts
Building Images	Docker Bake, Makefile targets, local vs production builds
Troubleshooting	Common issues and solutions for Docker deployments