ruvnet__ruflo/ruflo/docs/DOCKER.md

Docker Deployment Guide

Quick Start (Local / Self-Hosted)

# 1. Configure
cp .env.example .env
# Edit .env with your API keys

# 2. Generate config (for Cloud Run builds)
cp config/config.example.json config/config.json
# Edit config/config.json with your brand/model settings
node scripts/generate-config.js

# 3. Start
docker compose up -d

Open http://localhost:3000

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Chat UI    │────▶│  MCP Bridge  │────▶│   MongoDB    │
│  :3000       │     │  :3001       │     │  :27017      │
│              │     │              │     │              │
│  SvelteKit   │     │  Express.js  │     │  mongo:7     │
│  HF Chat UI  │     │  Proxy + MCP │     │  Persistence │
└──────────────┘     └──────────────┘     └──────────────┘
       │                    │
       │                    ├──▶ OpenAI API
       │                    ├──▶ Google Gemini API
       │                    └──▶ OpenRouter API
       │
       └── OPENAI_BASE_URL=http://mcp-bridge:3001

All model requests from Chat UI go through the MCP Bridge, which:

1. Resolves the correct upstream provider from the model name
2. Injects the server-side API key (never exposed to the client)
3. Proxies the OpenAI-compatible request to the upstream provider

Services

MongoDB (mongodb)

• Image: mongo:7
• Port: 27017
• Volume: mongo-data (persistent)
• Stores: conversations, user sessions, settings

MCP Bridge (mcp-bridge)

• Build: ./mcp-bridge/Dockerfile
• Port: 3001
• Healthcheck: /health
• Provides:
  • /chat/completions — OpenAI-compatible proxy (routes to Gemini/OpenAI/OpenRouter)
  • /mcp — MCP JSON-RPC endpoint for tool calls
  • /health — Health check

Chat UI (chat-ui)

• Build: ./chat-ui/Dockerfile (extends ghcr.io/huggingface/chat-ui-db:latest)
• Port: 3000
• Depends on: mongodb, mcp-bridge
• Config baked in via dotenv-local.txt → .env.local

Environment Variables

Required (at least one AI provider key)

Variable	Description
GOOGLE_API_KEY	Google Gemini API key
OPENAI_API_KEY	OpenAI API key
OPENROUTER_API_KEY	OpenRouter API key

Optional — Branding

Variable	Default	Description
BRAND_NAME	AI Assistant	App title
BRAND_DESCRIPTION	AI-powered assistant	App subtitle
PUBLIC_ORIGIN	http://localhost:3000	Public URL
MONGODB_DB_NAME	chat-db	MongoDB database name

Optional — Authentication (OIDC)

Variable	Description
OPENID_PROVIDER_URL	e.g., https://accounts.google.com
OPENID_CLIENT_ID	OAuth client ID
OPENID_CLIENT_SECRET	OAuth client secret
OPENID_SCOPES	Default: openid profile email
OPENID_NAME_CLAIM	Default: name
COOKIE_SECURE	true for HTTPS
COOKIE_SAMESITE	Default: lax

Optional — Backend Services

Variable	Description
SEARCH_API_URL	Your search/knowledge base endpoint
RESEARCH_API_URL	Your research/grounding endpoint

Common Operations

# Start all services
docker compose up -d

# View logs
docker compose logs -f
docker compose logs -f mcp-bridge   # specific service

# Restart after .env changes
docker compose up -d --force-recreate

# Rebuild after code changes
docker compose build --no-cache
docker compose up -d

# Stop
docker compose down

# Stop and remove data
docker compose down -v

Adding Models

Edit config/config.example.json → models array:

{
  "name": "gemini-2.5-pro",
  "displayName": "Gemini 2.5 Pro",
  "description": "Google's most capable model",
  "provider": "gemini",
  "supportsTools": true
}

Provider is resolved from the model name prefix:

• gemini-* → Google Generative Language API
• gpt-* → OpenAI API
• Everything else → OpenRouter API

Then regenerate and rebuild:

node scripts/generate-config.js
docker compose build chat-ui
docker compose up -d

Adding MCP Tools

Edit mcp-bridge/index.js:

1. Add your tool to the tools array
2. Add a handler in the tools/call switch
3. Rebuild: docker compose build mcp-bridge && docker compose up -d

Production (HTTPS + Domain)

For production, put a reverse proxy (nginx, Caddy, Traefik) in front:

# Add to docker-compose.yml
services:
  caddy:
    image: caddy:2
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy-data:/data
    depends_on:
      - chat-ui

volumes:
  caddy-data:

# Caddyfile
yourdomain.com {
    reverse_proxy chat-ui:3000
}

Set PUBLIC_ORIGIN=https://yourdomain.com and COOKIE_SECURE=true in .env.