This page provides a detailed technical guide to deploying RAGFlow using Docker Compose. It covers the service architecture, container configurations, environment variables, port mappings, and the deployment process. This guide is intended for technical operators and developers who want to self-host RAGFlow services in a containerized environment.
RAGFlow's Docker Compose deployment orchestrates multiple containerized components forming a complex application stack. The deployment consists of:
docker-compose.yml that manages the RAGFlow CPU/GPU application containers docker/docker-compose.yml1-126docker-compose-base.yml that manages dependency services like Elasticsearch, MySQL, MinIO, Redis, and alternative document engines docker/docker-compose-base.yml1-314This orchestrated stack delivers the full RAGFlow engine functionality including API servers, background task executors, data stores, and optional components like the Admin Server and MCP Server.
Sources: docker/docker-compose.yml1-126 docker/docker-compose-base.yml1-314 docker/README.md15-18 docker/.env8-28
The RAGFlow Docker Compose deployment is designed with a clear separation between client interaction, application logic, and persistence layers. This is articulated via multiple containers communicating over Docker networks and configured ports.
System Component Interaction Diagram
Key Points:
entrypoint.sh script dynamically selects the configuration (ragflow.conf.python, ragflow.conf.golang, or ragflow.conf.hybrid) based on the API_PROXY_SCHEME variable docker/entrypoint.sh190-206task_exe function in the entrypoint script initializes these workers with jemalloc for memory optimization docker/entrypoint.sh212-216mysql for metadata, minio for object storage, redis for task streaming, and one of several supported document engines docker/docker-compose-base.yml1-314elasticsearch, infinity, opensearch, oceanbase, seekdb), mutually exclusive to avoid conflict docker/.env13-20Sources: docker/docker-compose.yml1-126 docker/docker-compose-base.yml1-314 docker/entrypoint.sh11-216 docker/.env13-20 docker/README.md92-98 docker/docker-compose-base.yml158-185
RAGFlow supports multiple document storage backends. Docker Compose profiles control which engine runs docker/.env8-20:
| Service Name | Docker Image | Profile | Default Port Exposed | Description |
|---|---|---|---|---|
es01 | elasticsearch:8.11.3 | elasticsearch | ${ES_PORT}:9200 (default 1200) | Default full-text and vector search docker/.env31-38 |
infinity | infiniflow/infinity:v0.7.2-x64-v3 | infinity | ${INFINITY_THRIFT_PORT}:23817 | High-performance vector DB docker/.env67-72 |
opensearch01 | opensearchproject/opensearch:2.19.1 | opensearch | ${OS_PORT}:9201 | OpenSearch alternative docker/.env45-52 |
oceanbase | oceanbase/oceanbase-ce:4.4.1.0-100000032025101610 | oceanbase | ${OCEANBASE_PORT}:2881 | Distributed DB with vector support docker/.env75-82 |
seekdb | oceanbase/seekdb:latest | seekdb | ${SEEKDB_PORT}:2881 | Lightweight OceanBase variant docker/.env96-103 |
The environment variable DOC_ENGINE in .env picks the document engine, which sets the profile. Docker Compose activates profiles via COMPOSE_PROFILES=${DOC_ENGINE},${DEVICE} docker/.env20-28
Sources: docker/docker-compose-base.yml2-157 docker/.env8-103
MySQL (mysql service):
Hosts primary metadata such as datasets, users, and document indices.
mysql:8.0.40 docker/docker-compose-base.yml188rag_flow (configured via MYSQL_DBNAME) docker/.env1153306 docker/.env118
Sources: docker/docker-compose-base.yml187-213 docker/.env109-123MinIO (minio service):
Provides S3-compatible object storage for raw documents and parsed images.
pgsty/minio:RELEASE.2026-03-25T00-00-00Z docker/docker-compose-base.yml215MINIO_PORT default 9000) and Console (MINIO_CONSOLE_PORT default 9001) docker/.env129-132MINIO_USER, MINIO_PASSWORD docker/.env135-138
Sources: docker/docker-compose-base.yml215-234 docker/.env125-138Redis (redis service):
Utilized for task queues (via Redis Streams) and caching.
valkey:6.0.2 pyproject.toml1226379 docker/.env144
Sources: docker/docker-compose-base.yml236-256 docker/.env140-146 pyproject.toml122NATS (nats service):
A high-performance messaging system used for inter-service communication.
nats:2.10.17-alpine docker/docker-compose-base.yml2584222 docker/.env149
Sources: docker/docker-compose-base.yml258-266 docker/.env148-149ClickHouse (clickhouse service):
A column-oriented database management system used for analytics.
clickhouse/clickhouse-server:24.5 docker/docker-compose-base.yml268CLICKHOUSE_TCP_PORT default 9900), HTTP (CLICKHOUSE_HTTP_PORT default 8123) docker/.env154-155
Sources: docker/docker-compose-base.yml268-293 docker/.env151-162ragflow-cpu and ragflow-gpu are the main containers running the RAGFlow Python backend and task executors docker/docker-compose.yml21-126nvidia driver and gpu capabilities docker/docker-compose.yml119-126--enable-mcpserver) or Admin Server (--enable-adminserver) docker/entrypoint.sh11-33SVR_WEB_HTTP_PORT, SVR_HTTP_PORT, etc.) docker/docker-compose.yml49-55
Sources: docker/docker-compose.yml21-126 docker/entrypoint.sh11-33 docker/.env175-181RAGFlow uses a template-based system to generate its runtime service configuration (service_conf.yaml) from environment variables provided in .env.
Configuration Generation Flow
service_conf.yaml.template creating service_conf.yaml dynamically at container startup docker/entrypoint.sh163-182API_PROXY_SCHEME environment variable (python, go, or hybrid) docker/entrypoint.sh188-206HOST_ID using the system hostname or its MD5 hash if the hostname exceeds 32 characters docker/entrypoint.sh58-70
Sources: docker/entrypoint.sh1-216 docker/.env183-184Host system requirements pyproject.toml8:
3.13 pyproject.toml8Kernel configuration:
The kernel parameter vm.max_map_count must be at least 262144 for Elasticsearch and Infinity to work properly docker/README.md134-135
Check and set using docker/README.md138-140:
To make permanent, add to /etc/sysctl.conf docker/README.md146-148:
vm.max_map_count=262144
Sources: pyproject.toml8 docker/README.md134-148
Clone the repository and navigate to the docker folder:
Edit .env to configure settings such as RAGFLOW_IMAGE and DOC_ENGINE docker/.env20-27
Start the service stack:
Sources: docker/.env20-27
| Environment Variable | Default | Service Layer | Description |
|---|---|---|---|
SVR_WEB_HTTP_PORT | 80 | nginx (web proxy) | Public HTTP web UI and API docker/.env175 |
SVR_WEB_HTTPS_PORT | 443 | nginx (web proxy) | Public HTTPS web UI and API docker/.env176 |
SVR_HTTP_PORT | 9380 | Python backend API server | Internal API server port docker/.env177 |
ADMIN_SVR_HTTP_PORT | 9381 | Admin Server | Administrative API endpoint docker/.env178 |
SVR_MCP_PORT | 9382 | MCP Server | Model Context Protocol port docker/.env179 |
GO_HTTP_PORT | 9384 | Go server | Go-based backend API port docker/.env180 |
GO_ADMIN_PORT | 9383 | Go Admin server | Go-based Admin API port docker/.env181 |
MINIO_PORT | 9000 | MinIO object storage | S3 API port docker/.env132 |
ES_PORT | 1200 | Elasticsearch | Elasticsearch HTTP port docker/.env38 |
OS_PORT | 1201 | OpenSearch | OpenSearch HTTP port docker/.env45 |
INFINITY_THRIFT_PORT | 23817 | Infinity | Infinity Thrift API port docker/.env70 |
INFINITY_HTTP_PORT | 23820 | Infinity | Infinity HTTP API port docker/.env71 |
INFINITY_PSQL_PORT | 5432 | Infinity | Infinity PostgreSQL-compatible port docker/.env72 |
OCEANBASE_PORT | 2881 | OceanBase | OceanBase SQL port docker/.env78 |
SEEKDB_PORT | 2881 | SeekDB | SeekDB SQL port docker/.env99 |
EXPOSE_MYSQL_PORT | 3306 | MySQL | MySQL external access port docker/.env121 |
REDIS_PORT | 6379 | Redis | Redis external access port docker/.env144 |
NATS_PORT | 4222 | NATS | NATS messaging port docker/.env149 |
CLICKHOUSE_TCP_PORT | 9900 | ClickHouse | ClickHouse native TCP port docker/.env154 |
CLICKHOUSE_HTTP_PORT | 8123 | ClickHouse | ClickHouse HTTP port docker/.env155 |
JAEGER_OTLP_GRPC_PORT | 4317 | Jaeger (OpenTelemetry) | Jaeger OTLP gRPC port docker/.env169 |
JAEGER_OTLP_HTTP_PORT | 4318 | Jaeger (OpenTelemetry) | Jaeger OTLP HTTP port docker/.env170 |
JAEGER_UI_PORT | 16686 | Jaeger (OpenTelemetry) | Jaeger UI port docker/.env171 |
SANDBOX_EXECUTOR_MANAGER_PORT | 9385 | Sandbox Executor Manager | Sandbox service port docker/docker-compose-base.yml164 |
Sources: docker/.env33-181 docker/docker-compose.yml48-55 docker/docker-compose-base.yml164
RAGFlow uses Docker volumes and bind mounts to preserve data docker/docker-compose.yml56-62:
| Volume / Bind Mount | Usage | Location / Mapping |
|---|---|---|
./ragflow-logs | Log files | /ragflow/logs docker/docker-compose.yml57 |
./service_conf.yaml.template | Configuration template | /ragflow/conf/service_conf.yaml.template docker/docker-compose.yml61 |
./entrypoint.sh | Container startup script | /ragflow/entrypoint.sh docker/docker-compose.yml62 |
esdata01 | Elasticsearch data | /usr/share/elasticsearch/data docker/docker-compose-base.yml7 |
osdata01 | OpenSearch data | /usr/share/opensearch/data docker/docker-compose-base.yml45 |
infinity_data | Infinity data | /var/infinity docker/docker-compose-base.yml81 |
./infinity_conf.toml | Infinity configuration | /infinity_conf.toml docker/docker-compose-base.yml82 |
./oceanbase/data | OceanBase data | /root/ob docker/docker-compose-base.yml113 |
./oceanbase/conf | OceanBase configuration | /root/.obd/cluster docker/docker-compose-base.yml114 |
./oceanbase/init.d | OceanBase initialization scripts | /root/boot/init.d docker/docker-compose-base.yml115 |
./oceanbase-entrypoint.sh | OceanBase custom entrypoint | /root/boot/ragflow-oceanbase-entrypoint.sh docker/docker-compose-base.yml116 |
./seekdb | SeekDB data | /var/lib/oceanbase docker/docker-compose-base.yml140 |
mysql_data | MySQL data | /var/lib/mysql docker/docker-compose-base.yml203 |
./init.sql | MySQL initialization script | /data/application/init.sql docker/docker-compose-base.yml204 |
minio_data | MinIO data | /data docker/docker-compose-base.yml225 |
redis_data | Redis data | /data docker/docker-compose-base.yml245 |
nats_data | NATS data | /data docker/docker-compose-base.yml262 |
clickhouse_data | ClickHouse data | /var/lib/clickhouse docker/docker-compose-base.yml280 |
clickhouse_log | ClickHouse logs | /var/log/clickhouse-server docker/docker-compose-base.yml281 |
jaeger_data | Jaeger data | /var/lib/jaeger docker/docker-compose-base.yml306 |
Sources: docker/docker-compose.yml56-62 docker/docker-compose-base.yml1-314
MEM_LIMIT in .env docker/.env63-65--init-superuser to create default admin user docker/entrypoint.sh98-101huggingface.co access is limited, set HF_ENDPOINT in .env to a mirror site docker/README.md109-111MAX_CONTENT_LENGTH in .env and client_max_body_size in nginx/nginx.conf for larger file uploads docker/README.md120-122Sources: docker/README.md88-122 docker/docker-compose-base.yml158-185 docker/entrypoint.sh11-33 docker/.env63-65
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.