Building Images
FluidRAG uses Docker Buildx Bake for building images, with a Makefile that provides convenient wrappers. The build system supports local development (native platform) and production (linux/amd64) targets.
Image Overview
Section titled “Image Overview”FluidRAG consists of four Docker images:
| Image | Dockerfile | Build Context | Base |
|---|---|---|---|
fluidrag | ./Dockerfile | Project root | Python 3.12-slim (multi-stage) |
fluidrag-admin-api | services/config-api/Dockerfile | Project root | Node.js |
fluidrag-admin-ui | services/admin-ui/Dockerfile | services/admin-ui/ | Node.js + nginx |
fluidrag-gateway | services/gateway/Dockerfile | services/gateway/ | nginx |
The main fluidrag image uses a multi-stage build — a builder stage installs dependencies with uv, and the runtime stage copies only the virtual environment and application code.
Local Development Builds
Section titled “Local Development Builds”Build All Images
Section titled “Build All Images”make build-all-local VERSION=0.4.1This builds all four images for your native platform (ARM64 on Mac, AMD64 on Linux) and loads them into Docker.
Build Main API Only
Section titled “Build Main API Only”make build-local VERSION=0.4.1Use this when you’ve only changed backend Python code and don’t need to rebuild the admin UI or gateway.
No-Cache Build
Section titled “No-Cache Build”If code changes aren’t reflected in the container (stale cache):
make build-all-local-no-cache VERSION=0.4.1Lockfile Management
Section titled “Lockfile Management”When you change dependencies in pyproject.toml, regenerate the lockfile before building:
make uv-lockThe build-all-local target runs uv-lock automatically.
Production Builds
Section titled “Production Builds”Production builds target linux/amd64 and publish to GitHub Container Registry (GHCR).
Build for Production
Section titled “Build for Production”make build-prod VERSION=0.4.1Build and Publish
Section titled “Build and Publish”make build-publish-prod VERSION=0.4.1This pushes to ghcr.io/nodekat/fluidrag:0.4.1 and ghcr.io/nodekat/fluidrag:latest.
Build and Publish All Services
Section titled “Build and Publish All Services”make build-publish-all-prod-no-cache VERSION=0.4.1This builds and pushes all four images with no cache for maximum reproducibility:
ghcr.io/nodekat/fluidrag:0.4.1ghcr.io/nodekat/fluidrag-admin-api:0.4.1ghcr.io/nodekat/fluidrag-admin-ui:0.4.1ghcr.io/nodekat/fluidrag-gateway:0.4.1
Docker Bake Configuration
Section titled “Docker Bake Configuration”The build system is defined in docker-bake.hcl at the project root. Key targets:
| Bake Target | Platform | Cache | Purpose |
|---|---|---|---|
local | Native | Yes | Local development |
production | linux/amd64 | Yes (registry) | Production builds |
production-no-cache | linux/amd64 | No | Critical releases |
You can invoke Bake directly:
VERSION=0.4.1 docker buildx bake localVERSION=0.4.1 docker buildx bake productionMakefile Targets Reference
Section titled “Makefile Targets Reference”Service Management
Section titled “Service Management”| Target | Description |
|---|---|
make up | Start all services |
make down | Stop all services |
make logs | Follow all logs |
make logs-admin | Follow admin service logs |
Builds
Section titled “Builds”| Target | Description |
|---|---|
make build-local | Build API image (native, cached) |
make build-all-local | Build all images (native, cached) |
make build-all-local-no-cache | Build all images (native, no cache) |
make build-prod | Build API image (linux/amd64, cached) |
make build-publish-prod | Build and push API image |
make build-publish-all-prod-no-cache | Build and push all images (no cache) |
Version Override
Section titled “Version Override”All build targets accept a VERSION variable:
make build-local VERSION=0.4.1make build-prod VERSION=0.4.1Default version is defined in the Makefile (VERSION ?= 0.4.1).