This document provides comprehensive guidance for deploying RAGFlow using Docker Compose, including production deployment with pre-built images, configuration management, document engine selection, and building custom images. For information about the overall system architecture, see page 3. For details on frontend deployment and development workflows, see page 4.
Before deploying RAGFlow, ensure your system meets the following requirements:
| Resource | Minimum Requirement | Notes |
|---|---|---|
| CPU | 4 cores (x86) | ARM64 supported but requires custom image build |
| RAM | 16 GB | 8 GB per container via MEM_LIMIT in .env |
| Disk | 50 GB | Docker images expand to ~7 GB unpacked |
| Docker | >= 24.0.0 | - |
| Docker Compose | >= v2.26.1 | - |
vm.max_map_count | >= 262144 | Required for Elasticsearch/Infinity operation |
| gVisor | Optional | Only needed for sandbox (code executor) feature |
Critical System Configuration: The vm.max_map_count kernel parameter controls the maximum number of memory map areas a process may have. Both Elasticsearch and Infinity require this value to be at least 262144.
Sources: README.md145-178 docs/quickstart.mdx28-183
Docker Compose Service Orchestration
Startup Sequence: When docker compose up executes, the following occurs:
COMPOSE_PROFILES determines which document engine container starts (elasticsearch, infinity, opensearch, oceanbase, or seekdb)depends_on in docker/docker-compose.yml1-300 ensures MySQL, Redis, MinIO, and the selected doc engine start before the ragflow serviceenvsubst to replace ${VARIABLE} tokens in service_conf.yaml.template, generating /ragflow/conf/service_conf.yamlapi/ragflow_server.py - Quart web server listening on port 9380rag/svr/task_executor.py - Background worker for document processing tasksSources: docker/docker-compose.yml1-300 docker/docker-compose-base.yml1-250 docker/.env1-279 docker/entrypoint.sh1-100
The git checkout step ensures that the entrypoint.sh script in your local repository matches the Docker image version, preventing compatibility issues.
Sources: README.md180-206 docs/quickstart.mdx186-197
The docker/.env file controls all Docker-level configuration. Key variables:
Profile System: The COMPOSE_PROFILES variable activates specific services. For example, setting COMPOSE_PROFILES=elasticsearch,cpu,tei-cpu starts Elasticsearch (not Infinity), uses CPU for DeepDoc tasks, and enables the TEI embedding service.
Sources: docker/.env1-279 docker/README.md23-121
Verification:
Access RAGFlow: Navigate to http://YOUR_MACHINE_IP in a web browser. The default HTTP port 80 can be omitted from the URL.
Sources: README.md193-238 docs/quickstart.mdx198-248
Configuration Flow: When a container starts, entrypoint.sh runs envsubst to replace all ${VARIABLE} placeholders in service_conf.yaml.template with actual values from environment variables, generating the final service_conf.yaml file consumed by backend services.
Sources: docker/README.md122-198 docs/configurations.md14-30
The .env file defines Docker-level settings that affect container orchestration. Key variables referenced in docker/docker-compose.yml1-300:
| Category | Key Variables | Purpose | Code Reference |
|---|---|---|---|
| Engine Selection | DOC_ENGINE | Chooses between elasticsearch, infinity, opensearch, oceanbase, seekdb | COMPOSE_PROFILES=${DOC_ENGINE} activates corresponding profile |
| Image Versions | RAGFLOW_IMAGE, STACK_VERSION | Specifies Docker image tags | image: ${RAGFLOW_IMAGE} in compose file |
| Network Ports | SVR_HTTP_PORT, ES_PORT, MYSQL_PORT | External port mappings | ports: - "${ES_PORT}:9200" syntax |
| Authentication | MYSQL_PASSWORD, ELASTIC_PASSWORD, MINIO_PASSWORD, REDIS_PASSWORD | Service credentials | Passed as environment: vars to containers |
| Resource Limits | MEM_LIMIT, DOC_BULK_SIZE, EMBEDDING_BATCH_SIZE | Performance tuning | mem_limit: ${MEM_LIMIT} constraint |
| Optional Features | SANDBOX_ENABLED, REGISTER_ENABLED, USE_DOCLING | Feature flags | Read by api/ragflow_server.py via settings |
Critical Variables:
Docker Image Mirrors: If unable to download from Docker Hub, use alternative registries:
Sources: docker/.env1-279 docker/README.md23-121 docker/docker-compose.yml1-300
This template defines backend service connections consumed by api/ragflow_server.py and rag/svr/task_executor.py. The docker/entrypoint.sh1-100 script processes it using envsubst:
Configuration Loading Flow:
Variable Substitution: The envsubst utility replaces all ${VARIABLE} and ${VARIABLE:-default} patterns using environment variables from docker/.env. For example:
${MYSQL_PASSWORD} → infini_rag_flow (from .env)${MYSQL_HOST:-mysql} → mysql (default, or override from .env)Sources: docker/service_conf.yaml.template1-200 docker/entrypoint.sh1-100 docker/README.md122-198
The compose file orchestrates services with conditional profile activation:
Service Dependencies: The depends_on with condition: service_healthy ensures MySQL is ready before RAGFlow starts. Health checks defined via:
mysqladmin ping commandcurl http://localhost:9200curl http://localhost:23820/admin/node/currentProfile-Based Activation: The profiles: key controls service startup:
[""] → Always starts (ragflow, mysql, redis, minio)elasticsearch profile → Starts when COMPOSE_PROFILES includes "elasticsearch"infinity profile → Starts when COMPOSE_PROFILES includes "infinity"sandbox profile → Starts sandbox-executor-manager for code executionSetting COMPOSE_PROFILES=elasticsearch,cpu,tei-cpu in .env activates:
Sources: docker/docker-compose.yml1-300 docker/docker-compose-base.yml1-250 docker/README.md13-21
RAGFlow supports multiple pluggable document engines for storing full-text and vector embeddings. The engine is selected via DOC_ENGINE in .env and initialized in rag/nlp/rag_tokenizer.py1-100:
Document Store Connection Factory
Unified Interface: All connection classes implement common methods:
| Method | Purpose | Used By |
|---|---|---|
create_idx(kb_id, vector_size) | Create tenant index with vector field | api/db/services/knowledgebase_service.py |
insert(documents, kb_id) | Bulk insert chunks with embeddings | rag/svr/task_executor.py |
search(query_vector, kb_ids, top_k) | Hybrid vector + keyword search | rag/nlp/search.py |
update(chunk_id, fields) | Update chunk metadata | api/apps/document_app.py |
delete(kb_id, doc_ids) | Delete documents | api/db/services/document_service.py |
Index Naming Convention:
ragflow_{tenant_id} (e.g., ragflow_4fca7fc9c50f48e5be26c340e6b08a6f){tenant_id} in database default_db{engine}_doc_meta_{tenant_id} stores document-level infoSources: rag/nlp/rag_tokenizer.py1-500 rag/es_conn.py1-200 rag/infinity_conn.py1-200 docker/.env13-20
Prerequisites: This operation deletes all existing data in document stores. Back up if necessary.
What Changes:
Container Selection: COMPOSE_PROFILES=${DOC_ENGINE} in .env becomes COMPOSE_PROFILES=infinity,cpu, so Docker Compose starts the infinity service instead of es01
Connection Class: rag/nlp/rag_tokenizer.py50-100 reads DOC_ENGINE from conf/settings.py1-50 and instantiates InfinityConnection:
create_idx() call routes to the Infinity implementation:Infinity-Specific Configuration: The docker/infinity_conf.toml1-50 file configures Infinity's storage paths and network ports:
Sources: README.md273-294 docker/.env13-20 rag/nlp/rag_tokenizer.py1-500 docker/infinity_conf.toml1-50
| Feature | Elasticsearch | Infinity | OpenSearch |
|---|---|---|---|
| Architecture | REST API + Lucene | Thrift/HTTP/PSQL APIs | Fork of Elasticsearch |
| Ports | 9200 (HTTP) | 23817 (Thrift), 23820 (HTTP), 5432 (PSQL) | 9200 (HTTP) |
| Vector Support | Dense vector fields | Native vector columns | Dense vector fields |
| Full-Text | Lucene inverted index | SQL-based FTS | Lucene inverted index |
| ARM64 Support | Yes | Limited (not officially supported) | Yes |
| Memory Requirements | ~2-4 GB | ~1-2 GB | ~2-4 GB |
Sources: docker/.env13-73 README.md273-294
The Dockerfile1-215 uses a multi-stage build to minimize final image size while maintaining all dependencies:
Stage Dependency Flow
Key Build Components:
Lock File (uv.lock1-100000): Pin exact versions for reproducible builds
Pre-downloaded Models: The --mount=type=bind,from=infiniflow/ragflow_deps layer copies:
Frontend Build (web/package.json1-50 web/vite.config.ts1-50):
Image Size Breakdown:
Sources: Dockerfile1-215 pyproject.toml1-159 README.md296-313
The Dockerfile1-215 uses build arguments for mirror configuration:
Build Arguments (Dockerfile6-107):
Build Process:
ARM64 Build Notes:
onnxruntime-gpu → x86_64 onlyonnxruntime → arm64 compatibleSources: Dockerfile1-215 README.md296-313 docs/quickstart.mdx23-26
The pyproject.toml1-159 and uv.lock1-100000 files define all Python dependencies. The download_deps.py1-80 script handles non-PyPI assets:
uv Dependency Resolution:
pyproject.toml Key Dependencies (pyproject.toml9-159):
download_deps.py Script (download_deps.py1-80):
Downloads assets not available via PyPI:
uv.lock Format (uv.lock1-100): The lock file pins exact versions and hashes:
Sources: pyproject.toml1-159 uv.lock1-100 download_deps.py1-80 README.md317-330
Development Model: Backend services run natively on the host machine using a Python virtual environment, while infrastructure services (MySQL, Redis, MinIO, Elasticsearch) run in Docker containers. The frontend dev server proxies API requests to the local backend.
Sources: README.md315-385 docs/quickstart.mdx1-362
Step 1: Install Development Tools
Step 2: Clone and Install Python Dependencies
Step 3: Start Infrastructure Services
Step 4: Configure Host Resolution
Add the following line to /etc/hosts:
127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager
This allows backend services to resolve container hostnames to localhost.
Step 5: Install jemalloc (if missing)
Step 6: Start Backend Services
The launch_backend_service.sh script starts two processes:
ragflow_server.py: Quart API server on port 9380task_executor.py: Document processing workerStep 7: Start Frontend Development Server
The Vite dev server starts on port 5173 with hot module replacement.
Step 8: Access Development Instance
Navigate to http://localhost:5173 in your browser. The frontend proxies API requests to http://localhost:9380.
Step 9: Stop Services
Sources: README.md315-385 docs/quickstart.mdx1-362
conf/service_conf.yaml (for local development):
web/vite.config.ts (frontend proxy configuration):
Sources: docker/service_conf.yaml.template1-200 web/vite.config.ts1-50
Symptom: Logs show Can't connect to ES cluster error.
Cause: vm.max_map_count is less than 262144.
Solution:
Sources: README.md158-178 docs/quickstart.mdx44-183
Symptom: Browser displays "network abnormal" when accessing RAGFlow.
Cause: RAGFlow container is not fully initialized yet.
Solution: Wait for the ASCII art banner to appear in logs:
Sources: README.md220-238 docs/quickstart.mdx222-242
Symptom: docker compose up fails to pull RAGFlow image.
Solution: Use alternative mirrors in docker/.env:
Sources: docker/.env156-166 docker/README.md84-91
Symptom: Docker Compose fails on ARM64 machines (Apple Silicon, AWS Graviton).
Cause: Official images are built for x86 only.
Solution: Build a custom ARM64 image:
Sources: README.md187-189 docs/quickstart.mdx23-26
Data Preservation: Upgrading RAGFlow does not delete uploaded files or datasets. However, using docker compose down -v will delete all Docker volumes and cause data loss.
Sources: docs/guides/upgrade_ragflow.mdx1-102
Nightly vs. Stable: The nightly tag represents the most recent build from the main branch and may contain unstable features. Use stable releases (e.g., v0.24.0) for production.
Sources: docs/guides/upgrade_ragflow.mdx18-47
Sources: docs/guides/upgrade_ragflow.mdx90-101
After successful deployment, configure LLM providers and system models via the web interface:
Alternatively, pre-configure the default LLM in service_conf.yaml.template:
Sources: README.md244-249 docs/quickstart.mdx250-272
This document covered the complete deployment lifecycle for RAGFlow:
vm.max_map_count configuration.env, service_conf.yaml.template, docker-compose.yml hierarchyFor information about system architecture and component interactions, see page 3. For details on API deployment and SDK usage, see page 7.
Sources: README.md1-411 docs/quickstart.mdx1-362 docker/README.md1-340
Refresh this wiki