ContextQMD
Back to Ruflo

Docker Deployment Guide

ruflo/docs/DOCKER.md

3.10.55.0 KB
Original Source

Docker Deployment Guide

Quick Start (Local / Self-Hosted)

bash
# 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)

VariableDescription
GOOGLE_API_KEYGoogle Gemini API key
OPENAI_API_KEYOpenAI API key
OPENROUTER_API_KEYOpenRouter API key

Optional — Branding

VariableDefaultDescription
BRAND_NAMEAI AssistantApp title
BRAND_DESCRIPTIONAI-powered assistantApp subtitle
PUBLIC_ORIGINhttp://localhost:3000Public URL
MONGODB_DB_NAMEchat-dbMongoDB database name

Optional — Authentication (OIDC)

VariableDescription
OPENID_PROVIDER_URLe.g., https://accounts.google.com
OPENID_CLIENT_IDOAuth client ID
OPENID_CLIENT_SECRETOAuth client secret
OPENID_SCOPESDefault: openid profile email
OPENID_NAME_CLAIMDefault: name
COOKIE_SECUREtrue for HTTPS
COOKIE_SAMESITEDefault: lax

Optional — Backend Services

VariableDescription
SEARCH_API_URLYour search/knowledge base endpoint
RESEARCH_API_URLYour research/grounding endpoint

Common Operations

bash
# 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:

json
{
  "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:

bash
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:

yaml
# 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.