RAGFlow - Open-source RAG engine with Agent capabilities

# Check current vm.max_map_count value
sysctl vm.max_map_count

# Set to required minimum (262144)
sudo sysctl -w vm.max_map_count=262144

# Make the change permanent (survives reboot)
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf

# Verify the change
sysctl vm.max_map_count

# Clone the repository
git clone https://github.com/infiniflow/ragflow.git
cd ragflow/

# Optional: checkout a stable release tag
# git checkout v0.25.6
# This ensures the entrypoint.sh matches the Docker image version

# Navigate to docker directory
cd docker/

# Start all services (CPU mode)
docker compose -f docker-compose.yml up -d

# Monitor startup logs (wait for "Running on all addresses (0.0.0.0)")
docker logs -f docker-ragflow-cpu-1

# Expected output when ready:
#      ____   ___    ______ ______ __
#     / __ \ /   |  / ____// ____// /____  _      __
#    / /_/ // /| | / / __ / /_   / // __ \| | /| / /
#   / _, _// ___ |/ /_/ // __/  / // /_/ /| |/ |/ /
#  /_/ |_|/_/  |_|\____//_/    /_/ \____/ |__/|__/
#
# * Running on all addresses (0.0.0.0)

# Install NVIDIA Container Toolkit (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

# Verify GPU is accessible
nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

# Navigate to docker directory
cd ragflow/docker/

# Enable GPU mode by uncommenting DEVICE=gpu in .env
sed -i '1i DEVICE=gpu' .env

# Start with GPU support
docker compose -f docker-compose.yml up -d

# Verify GPU is being used
docker logs docker-ragflow-gpu-1 | grep -i cuda

# With default settings (port 80):
# Open browser to: http://localhost
# Or from another machine: http://<SERVER_IP>

# To check which port is configured:
grep SVR_WEB_HTTP_PORT docker/.env

# Default .env values:
# SVR_WEB_HTTP_PORT=80     # HTTP
# SVR_WEB_HTTPS_PORT=443   # HTTPS (if configured)
# SVR_HTTP_PORT=9380       # API endpoint
# SVR_MCP_PORT=9382        # MCP server

# First-time login creates an admin account

# Edit docker/service_conf.yaml.template
# Set the default LLM and add your API key

# Example for OpenAI:
user_default_llm:
  factory: "OpenAI"
  api_key: "sk-your-openai-api-key-here"
  base_url: "https://api.openai.com/v1"  # optional

# Example for Anthropic Claude:
user_default_llm:
  factory: "Anthropic"
  api_key: "sk-ant-your-anthropic-api-key"

# Example for local Ollama:
user_default_llm:
  factory: "Ollama"
  base_url: "http://host.docker.internal:11434"

# After editing, restart the container:
# docker compose -f docker-compose.yml restart ragflow-cpu

# Stop all running containers (WARNING: -v deletes volumes)
cd ragflow/docker/
docker compose -f docker-compose.yml down -v

# Edit .env to enable Infinity
sed -i 's/DOC_ENGINE=.*/DOC_ENGINE=infinity/' .env

# Verify the change
grep DOC_ENGINE .env
# Expected: DOC_ENGINE=infinity

# Start with Infinity backend
docker compose -f docker-compose.yml up -d

# Check Infinity health
docker logs docker-infinity-1

# Generate strong passwords
openssl rand -base64 32  # Use output for MYSQL_PASSWORD
openssl rand -base64 32  # Use output for MINIO_PASSWORD
openssl rand -base64 32  # Use output for REDIS_PASSWORD

# Edit docker/.env with your production values
vi docker/.env

# Example production .env snippet:
# SVR_WEB_HTTP_PORT=80
# MYSQL_PASSWORD=<strong-password-here>
# MINIO_PASSWORD=<strong-password-here>
# REDIS_PASSWORD=<strong-password-here>
# MEM_LIMIT=16g

# Start with production config
docker compose -f docker-compose.yml up -d

# Install gVisor (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL https://gvisor.dev/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main" | sudo tee /etc/apt/sources.list.d/gvisor.list > /dev/null
sudo apt-get update
sudo apt-get install -y runsc

# Configure Docker to use gVisor (optional)
sudo runsc install
sudo systemctl restart docker

# Enable sandbox in docker-compose.yml by uncommenting the sandbox profile
cd ragflow/docker/
vi docker-compose-base.yml
# Ensure 'sandbox-executor-manager' service is enabled

# Start with sandbox enabled
docker compose --profile sandbox -f docker-compose.yml up -d

# Verify sandbox manager is running
docker logs docker-sandbox-executor-manager-1

# Edit docker/docker-compose.yml to enable MCP server
# Uncomment the MCP command section:

services:
  ragflow-cpu:
    command:
      - --enable-mcpserver
      - --mcp-host=0.0.0.0
      - --mcp-port=9382
      - --mcp-base-url=http://127.0.0.1:9380
      - --mcp-script-path=/ragflow/mcp/server/server.py
      - --mcp-mode=self-host
      - --mcp-host-api-key=ragflow-<your-secret-key-here>
      # Disable SSE transport (keep only Streamable HTTP):
      # - --no-transport-sse-enabled

# Restart to apply:
# docker compose -f docker-compose.yml up -d

# MCP endpoint is now available at:
# http://<server-ip>:9382/mcp

# Example: Sync from S3 bucket
# 1. Add S3 credentials in RAGFlow UI:
#    - Settings → Data Sources → Add S3
#    - Enter: Bucket name, Access Key ID, Secret Access Key, Region
#
# 2. Create knowledge base:
#    - Knowledge Bases → New → Select S3 connector
#    - Configure file filters (e.g., *.pdf, *.docx)
#    - Set sync interval: daily at 2 AM UTC
#
# 3. RAGFlow will:
#    - Download files matching filters
#    - Process documents with DeepDoc pipeline
#    - Chunk, embed, and index into vector database
#    - Track sync state (last sync time, new files, errors)

# Monitor sync logs:
docker logs -f docker-ragflow-cpu-1 | grep -i "sync"

# Step 1: Create a knowledge base via UI
# - Navigate to Knowledge Bases → New
# - Name: "Technical Documentation"
# - Parsing method: Advanced (MinerU)
# - Chunking: Template (Sections)
# - Embedding model: all-MiniLM-L6-v2

# Step 2: Upload documents
# - Click "Upload" → Select PDFs, DOCX, web pages
# - RAGFlow processes in background (check Status column)
# - View chunks: Click document → Chunks tab → Visual chunk editor

# Step 3: Create an agent
# - Agents → New Agent
# - Name: "Tech Support Assistant"
# - System prompt: "You are a helpful technical support agent. Use retrieved context to answer questions accurately."
# - Attach knowledge base: Select "Technical Documentation"
# - Retrieval settings: Top-K = 5, Similarity threshold = 0.7
# - Enable citations: Show source references

# Step 4: Chat interface
# - Open agent chat
# - Ask: "How do I configure the vector database?"
# - Response includes grounded citations with chunk references
# - Click citation to see original document chunk

# Step 5: API integration (optional)
# curl -X POST http://localhost:9380/api/v1/chat \
#   -H "Authorization: Bearer <api-key>" \
#   -H "Content-Type: application/json" \
#   -d '{
#     "agent_id": "<agent-uuid>",
#     "messages": [{"role": "user", "content": "How do I configure the vector database?"}]
#   }'

# Example Kubernetes deployment (Helm chart available)
# Install with Helm:
helm repo add ragflow https://infiniflow.github.io/ragflow-helm
helm install ragflow ragflow/ragflow \
  --set mysql.external.enabled=true \
  --set mysql.external.host=mysql.prod.example.com \
  --set mysql.external.password=<password> \
  --set elasticsearch.external.enabled=true \
  --set elasticsearch.external.host=https://es.prod.example.com:9200 \
  --set minio.external.enabled=true \
  --set minio.external.endpoint=s3.amazonaws.com \
  --set minio.external.bucket=ragflow-prod \
  --set replicas=5

# Autoscaling with HPA:
kubectl autoscale deployment ragflow \
  --cpu-percent=70 \
  --min=3 \
  --max=20

# Enable OpenTelemetry in service_conf.yaml.template
opentelemetry:
  enabled: true
  exporter: otlp
  endpoint: http://otel-collector:4317
  service_name: ragflow

# Prometheus metrics endpoint (after enabling):
# http://localhost:9380/metrics

# Key metrics to monitor:
# - ragflow_documents_processed_total (counter)
# - ragflow_chunk_count (gauge)
# - ragflow_query_latency_seconds (histogram)
# - ragflow_embedding_batch_size (histogram)
# - ragflow_llm_token_usage_total (counter)
# - ragflow_vector_search_latency_seconds (histogram)

# Sample Prometheus scrape config:
# scrape_configs:
#   - job_name: 'ragflow'
#     static_configs:
#       - targets: ['ragflow:9380']

# Install uv and pre-commit
pipx install uv pre-commit

# Clone repository
git clone https://github.com/infiniflow/ragflow.git
cd ragflow/

# Create Python virtual environment and install dependencies
uv sync --python 3.13
uv run python3 download_deps.py  # Downloads models and resources
pre-commit install

# Start infrastructure services only (MySQL, Redis, MinIO, Elasticsearch)
docker compose -f docker/docker-compose-base.yml up -d

# Add hosts to /etc/hosts
echo "127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager" | sudo tee -a /etc/hosts

# Set HuggingFace mirror (if needed)
export HF_ENDPOINT=https://hf-mirror.com

# Install jemalloc (memory allocator)
sudo apt-get install -y libjemalloc-dev  # Ubuntu/Debian

# Activate virtual environment and start backend
source .venv/bin/activate
export PYTHONPATH=$(pwd)
bash docker/launch_backend_service.sh &

# In another terminal, start frontend
cd web/
npm install
npm run dev

# Access at http://localhost:5173 (Vite dev server)

# Stop services when done
pkill -f "ragflow_server.py|task_executor.py"
docker compose -f docker/docker-compose-base.yml down

# Check container health
docker ps --filter name=ragflow

# View logs for specific service
docker logs docker-ragflow-cpu-1 --tail 100 -f
docker logs docker-es01-1 --tail 100 -f
docker logs docker-mysql-1 --tail 100 -f

# Restart specific service
docker compose -f docker/docker-compose.yml restart ragflow-cpu

# Check resource usage
docker stats

# Verify connectivity between services
docker exec -it docker-ragflow-cpu-1 ping es01
docker exec -it docker-ragflow-cpu-1 nc -zv mysql 3306

# Reset entire stack (WARNING: deletes all data)
cd docker/
docker compose -f docker-compose.yml down -v
docker compose -f docker-compose.yml up -d

import requests

API_BASE = "http://localhost:9380/api/v1"
API_KEY = "your-api-key-here"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Create knowledge base
resp = requests.post(f"{API_BASE}/dataset", json={
    "name": "Product Docs",
    "chunk_method": "general",
    "embedding_model": "all-MiniLM-L6-v2"
}, headers=headers)
dataset_id = resp.json()["id"]

# Upload document
with open("manual.pdf", "rb") as f:
    files = {"file": f}
    resp = requests.post(
        f"{API_BASE}/dataset/{dataset_id}/document",
        files=files,
        headers=headers
    )
doc_id = resp.json()["id"]

# Wait for processing (poll status)
import time
while True:
    resp = requests.get(f"{API_BASE}/document/{doc_id}", headers=headers)
    status = resp.json()["status"]
    if status == "completed":
        break
    time.sleep(5)

# Query the knowledge base
resp = requests.post(f"{API_BASE}/retrieval", json={
    "dataset_id": dataset_id,
    "query": "How do I reset my password?",
    "top_k": 5
}, headers=headers)
chunks = resp.json()["chunks"]
for chunk in chunks:
    print(f"Score: {chunk['score']:.3f} | {chunk['text'][:100]}...")

# Install RAGFlow skill in OpenClaw
# Visit: https://clawhub.ai/yingfeng/ragflow-skill

# Or add to OpenClaw config.yaml:
skills:
  - name: ragflow
    source: clawhub://yingfeng/ragflow-skill
    config:
      endpoint: http://localhost:9380
      api_key: your-ragflow-api-key
      default_dataset_id: <your-dataset-uuid>

# Example OpenClaw agent using RAGFlow:
# agent:
#   name: customer_support
#   skills:
#     - ragflow
#   prompt: |
#     You are a customer support agent.
#     Use the ragflow_search tool to find relevant information from our knowledge base.
#     Always cite your sources.