Getting Started and Deployment

Relevant source files

• .github/workflows/tests.yml
• Dockerfile
• README.md
• README_ar.md
• README_fr.md
• README_id.md
• README_ja.md
• README_ko.md
• README_pt_br.md
• README_tr.md
• README_tzh.md
• README_zh.md
• docker/.env
• docker/README.md
• docker/docker-compose-base.yml
• docker/docker-compose.yml
• docker/entrypoint.sh
• docker/infinity_conf.toml
• docs/guides/manage_files.md
• docs/quickstart.mdx
• helm/values.yaml
• mcp/client/client.py
• mcp/client/streamable_http_client.py
• mcp/server/server.py
• pyproject.toml
• sdk/python/pyproject.toml
• sdk/python/uv.lock
• test/unit_test/mcp/test_document_metadata_pagination.py
• test/unit_test/mcp/test_server_datasets.py
• uv.lock

This document provides a high-level overview of RAGFlow's deployment options and initial setup procedures. It outlines the system prerequisites, primary deployment methods, and the essential configuration files used to run RAGFlow. For in-depth instructions and technical details, please refer to the dedicated child pages:

• Docker Compose Deployment — Detailed guide for deploying RAGFlow using Docker Compose, including service architecture, container configuration, and port mappings.
• Configuration Management — Explain the configuration system including service_conf.yaml, environment variables, and the relationship between configuration sources.
• Document Engine Selection — Guide for choosing and configuring document engines (Elasticsearch, Infinity, OpenSearch) with their tradeoffs.
• Build System and CI/CD — Explain the build pipeline, dependency management with uv, multi-language compilation (Python, Go, C++), and GitHub Actions testing workflow.
• Kubernetes and Helm Deployment — Document the Helm chart structure for Kubernetes deployment, including templates for all services, ingress configuration, and values.yaml customization.

---

Deployment Architecture Overview

RAGFlow utilizes a containerized microservices architecture with each major service encapsulated in its own Docker container or Kubernetes pod. This modular design separates core application logic, data infrastructure, and optional extensions, allowing flexibility in scaling and customization.

Containerized Service Architecture

Sources: docker/docker-compose-base.yml1-240 docker/.env1-185

This architecture highlights the clear separation of concerns:

• RAGFlow CPU container: Hosts the core Python-based API server and task executor workers.
• Elasticsearch / Alternative Vector DB: Used for document indexing and vector-based search docker/.env13-20
• MySQL: Metadata and configuration storage docker/.env109-115
• MinIO: Object storage for files and blobs docker/.env125-132
• Redis: Serves as cache, session store, and supports asynchronous task queueing via Redis Streams docker/.env140-146
• Optional containers: Include alternative document engines, sandbox executor for safe code evaluation docker/docker-compose-base.yml158-184 and ClickHouse for analytics docker/.env151-162

Sources: docker/docker-compose-base.yml1-240 docker/.env1-185 README.md141-145

---

Configuration Management Overview

RAGFlow’s configuration is managed through multiple layers, typically involving environment variables, templated YAML files, and Docker Compose profiles to tailor container orchestration.

Configuration Relationships

Sources: docker/.env1-185 docker/docker-compose-base.yml1-240

• The .env file defines environment variables controlling service behavior and credentials docker/.env1-6
• service_conf.yaml.template uses variables from .env to build the runtime service configuration.
• docker-compose.yml reads .env variables and manages container lifecycle and profiles docker/docker-compose-base.yml1-5
• Different DOC_ENGINE values in .env control which document store profile and container are started (e.g., elasticsearch, infinity, oceanbase, opensearch, seekdb) docker/.env13-20

Sources: docker/.env1-185 docker/docker-compose-base.yml1-240

---

System Prerequisites

RAGFlow requires specific hardware and software environments to run efficiently.

Hardware Requirements

Component	Minimum Requirement
CPU	x86 Architecture, ≥ 4 cores
RAM	≥ 16 GB
Disk	≥ 50 GB free space

Note: Official Docker images are built exclusively for x86 platforms README_zh.md191-193 ARM64 users need to build from source using the provided build scripts docs/quickstart.mdx23-26

Sources: README_zh.md148-155 docs/quickstart.mdx28-35

Software Requirements

Software	Version Requirement
Docker	≥ 24.0.0
Docker Compose	≥ v2.26.1
Python	≥ 3.13
gVisor	Optional (for sandbox code executor feature)

Sources: README_zh.md148-155 docs/quickstart.mdx28-35 pyproject.toml8

Kernel Configuration

A crucial step for document engines like Elasticsearch and Infinity is the system kernel parameter vm.max_map_count, which must be set to at least 262144 docs/quickstart.mdx45-52

Sources: README_zh.md162-181 docs/quickstart.mdx44-82

---

Deployment Methods

RAGFlow supports multiple deployment methods tailored to production, development, or specialized environments.

1. Docker Compose Deployment (Recommended)

This method uses pre-built Docker images managed through Docker Compose for complete service orchestration.

• Docker images are tagged (e.g., v0.26.4) README.md28
• The DOC_ENGINE environment variable in .env controls which document engine profile and container are launched docker/.env13-20
• Deployment profiles are generated based on DOC_ENGINE and DEVICE (CPU/GPU) settings docker/.env28

For details, see Docker Compose Deployment.

Sources: README.md162-182 docker/.env13-170

2. Source-Based Deployment (For Development)

This method runs RAGFlow services directly from the source code:

• Python environment managed using uv Dockerfile77-91 with dependencies locked via uv.lock uv.lock1-10 and defined in pyproject.toml pyproject.toml9-181
• Multi-language build support: Go, and Python .github/workflows/tests.yml132-142
• Supporting data infrastructure (MySQL, Redis, MinIO) still runs as Docker containers.

For details, see Build System and CI/CD.

Sources: README.md162-182 Dockerfile77-91 .github/workflows/tests.yml130-143

3. Kubernetes and Helm Deployment

Enterprise-scale deployments can leverage Helm charts and Kubernetes for orchestration of all RAGFlow components including Redis, MySQL, MinIO, and Document Stores.

For details, see Kubernetes and Helm Deployment.

Sources: helm/values.yaml1-50

---

RAGFlow Service Architecture and Data Flow

Sources: docker/docker-compose-base.yml5-240 docker/.env140-163 pyproject.toml1-181

• The Python Quart app handles HTTP and API requests pyproject.toml147
• Background workers consume task streams from Redis for asynchronous processing.
• The Go server component supports native services and improved performance docker/.env180-181
• API_PROXY_SCHEME can be set to hybrid to enable both Go and Python backend layers docker/.env183

Sources: docker/docker-compose-base.yml5-240 docker/.env140-163 pyproject.toml1-181

---

Document Engine Selection

RAGFlow supports multiple document search engines. The choice is controlled by the DOC_ENGINE environment variable in .env. Available options include:

• Elasticsearch (Default) docker/.env20
• Infinity docker/.env16
• OceanBase docker/.env17
• OpenSearch docker/.env18
• SeekDB docker/.env19

For details, see Document Engine Selection.

Sources: docker/.env13-20 docker/docker-compose-base.yml3-157

---

Build System and Continuous Integration

The RAGFlow source supports complex multi-language builds:

• Python: Dependencies and environment are managed via uv Dockerfile77-91 with pyproject.toml pyproject.toml1-181
• Go: Services are built for high-performance ingestion and server logic.
• CI/CD: GitHub Actions workflows automate preflight checks, unit tests, and integration tests across different document engines .github/workflows/tests.yml31-154

For details, see Build System and CI/CD.

Sources: Dockerfile77-91 .github/workflows/tests.yml31-154 pyproject.toml1-201