This document describes how to deploy RAGFlow using Docker Compose, covering both production deployments using pre-built Docker images and development deployments from source code. For information about individual configuration options, see Configuration Management. For details about selecting between document engines, see Document Engine Selection.
RAGFlow provides two primary Docker Compose configurations:
The system uses Docker Compose profiles to selectively enable services based on configuration choices specified in docker/.env20-28
Before deploying RAGFlow, ensure your system meets these requirements:
| Requirement | Minimum Specification |
|---|---|
| CPU | ≥ 4 cores (x86_64 or ARM64) |
| RAM | ≥ 16 GB |
| Disk | ≥ 50 GB |
| Docker | ≥ 24.0.0 |
| Docker Compose | ≥ v2.26.1 |
Platform Support:
System Configuration:
The vm.max_map_count kernel parameter must be set to at least 262144 for Elasticsearch/Infinity to function properly README.md158-178:
Sources: README.md146-155 docker/.env1-279 docs/quickstart.mdx28-38
Deployment Steps:
Clone the repository README.md182-184:
Switch to stable version README.md196-198:
Start services README.md200-206:
Verify deployment README.md217-237:
Look for the RAGFlow ASCII art banner indicating successful startup.
Sources: README.md180-250 docs/quickstart.mdx186-234
Service Descriptions:
| Service | Image | Purpose | Required |
|---|---|---|---|
ragflow | infiniflow/ragflow:v0.24.0 | Main application server | Yes |
es01 / infinity / opensearch01 | Varies by profile | Document and vector storage | Yes (one) |
mysql | mysql:8.0.39 | Relational metadata storage | Yes |
minio | quay.io/minio/minio | Object storage for files | Yes |
redis | valkey:8 | Cache and task queue | Yes |
tei | infiniflow/text-embeddings-inference | Embedding service | Optional |
sandbox-executor-manager | infiniflow/sandbox-executor-manager | Code execution sandbox | Optional |
Sources: docker/docker-compose-base.yml1-280 docker/.env13-28
RAGFlow uses Docker Compose profiles to conditionally enable services based on the COMPOSE_PROFILES environment variable docker/.env28
Profile Configuration:
The COMPOSE_PROFILES variable is automatically constructed from docker/.env28:
Available Profiles:
Document Engine Profiles (mutually exclusive) docker/.env13-20:
elasticsearch: Elasticsearch 8.11.3 for full-text and vector searchinfinity: Infinity v0.7.0 for SQL+vector databaseopensearch: OpenSearch 2.19.1 as ES alternativeoceanbase: OceanBase 4.4.1 distributed databaseseekdb: SeekDB vector databaseDevice Profiles docker/.env22-26:
cpu: CPU-only inference for DeepDoc tasks (default)gpu: GPU acceleration for document processingOptional Feature Profiles docker/.env169-239:
tei-cpu: Text embeddings inference on CPUtei-gpu: Text embeddings inference on GPUsandbox: Code executor with gVisor isolationkibana: Elasticsearch management interfaceEnabling Multiple Profiles:
Sources: docker/.env13-239 docker/docker-compose-base.yml3-74
1. docker/.env docker/.env1-279
Primary environment configuration file containing:
RAGFLOW_IMAGE, STACK_VERSION)ELASTIC_PASSWORD, MYSQL_PASSWORD, MINIO_PASSWORD, REDIS_PASSWORD)*_PORT variables)DOC_ENGINE, DEVICE, REGISTER_ENABLED)MEM_LIMIT, DOC_BULK_SIZE, EMBEDDING_BATCH_SIZE)2. docker/service_conf.yaml.template docker/service_conf.yaml.template
Backend service configuration template with variable substitution README.md258:
${MYSQL_HOST}, ${MYSQL_PORT}, etc.llm_factories.json reference)DOC_ENGINE)minio, S3, OSS, Azure)3. docker/docker-compose.yml
Service orchestration file defining:
Sources: README.md252-262 docker/.env1-279 docker/README.md13-19
RAGFlow Application Ports docker/.env148-154:
| Environment Variable | Default | Container Port | Purpose |
|---|---|---|---|
SVR_WEB_HTTP_PORT | 80 | 80 | HTTP web interface |
SVR_WEB_HTTPS_PORT | 443 | 443 | HTTPS web interface |
SVR_HTTP_PORT | 9380 | 9380 | HTTP API endpoint |
ADMIN_SVR_HTTP_PORT | 9381 | 9381 | Admin API endpoint |
SVR_MCP_PORT | 9382 | 9382 | MCP (Model Context Protocol) server |
Dependency Service Ports docker/.env38-187:
| Service | Variable | Default | Purpose |
|---|---|---|---|
| Elasticsearch | ES_PORT | 1200 | HTTP API |
| OpenSearch | OS_PORT | 1201 | HTTP API |
| Infinity | INFINITY_THRIFT_PORT | 23817 | Thrift protocol |
| Infinity | INFINITY_HTTP_PORT | 23820 | HTTP API |
| Infinity | INFINITY_PSQL_PORT | 5432 | PostgreSQL protocol |
| MySQL | EXPOSE_MYSQL_PORT | 5455 | External access |
| MinIO | MINIO_PORT | 9000 | API endpoint |
| MinIO | MINIO_CONSOLE_PORT | 9001 | Web console |
| Redis | REDIS_PORT | 6379 | Redis protocol |
| TEI | TEI_PORT | 6380 | Embedding service |
| Kibana | KIBANA_PORT | 6601 | Web interface |
| Sandbox | SANDBOX_EXECUTOR_MANAGER_PORT | 9385 | Code executor API |
Changing Default Ports:
To modify the HTTP web port from 80 README.md264-266:
Sources: docker/.env148-187 README.md264-271 docker/README.md25-73
Named Volumes docker/docker-compose-base.yml7-272:
| Volume | Service | Purpose | Data Type |
|---|---|---|---|
esdata01 | es01 | Elasticsearch indices | Document vectors and metadata |
osdata01 | opensearch01 | OpenSearch indices | Document vectors and metadata |
infinity_data | infinity | Infinity database | Document vectors and metadata |
mysql_data | mysql | MySQL database | User accounts, KB configs, tasks |
redis_data | redis | Redis persistence | AOF/RDB files |
Volume Lifecycle:
Warning: Using docker compose down -v deletes all volumes and data docs/guides/upgrade_ragflow.mdx15:
Backup Strategy:
To back up persistent data before upgrades:
Sources: docker/docker-compose-base.yml7-272 docs/guides/upgrade_ragflow.mdx15
Health Check Specifications docker/docker-compose-base.yml27-266:
Each service implements health checks with these parameters:
Example Health Check Definitions:
Verifying Service Health:
Sources: docker/docker-compose-base.yml27-201 README.md217-237
For developers who want to modify RAGFlow code and run services locally without Docker for the main application.
1. Install development tools README.md317-321:
2. Clone and install dependencies README.md322-330:
3. Start dependency services only README.md331-335:
This starts only ES/Infinity, MySQL, MinIO, and Redis—not the RAGFlow application itself docker/docker-compose-base.yml1-280
4. Configure hostname resolution README.md337-341:
5. Optional: Set HuggingFace mirror README.md342-346:
6. Install jemalloc (if needed) README.md347-358:
7. Start backend services README.md359-365:
This script starts:
api/ragflow_server.py: Main API server (Quart application)rag/svr/task_executor.py: Document processing worker8. Install and start frontend README.md366-380:
The frontend dev server runs on port 5173 with hot reloading.
9. Stop services after development README.md381-386:
Development vs. Production Differences:
| Aspect | Development | Production |
|---|---|---|
| RAGFlow app | Native Python process | Docker container |
| Frontend | Dev server (port 5173) | Built static files via nginx |
| Hot reload | Enabled | Disabled |
| Dependencies | Docker containers | Docker containers |
| Configuration | conf/service_conf.yaml | Generated from template |
Sources: README.md315-386 docker/docker-compose-base.yml1-280
RAGFlow supports multiple document storage backends. Switching requires data migration.
Switching from Elasticsearch to Infinity README.md273-294:
Stop all containers (data will be deleted):
Update engine selection docker/.env20:
Restart services:
The COMPOSE_PROFILES variable automatically updates to activate the infinity profile and deactivate elasticsearch docker/.env28
Platform Limitations:
Sources: README.md273-294 docker/.env13-20
RAGFlow Image Versions docker/.env156-165:
| Image Tag | Repository | Size | Stability | Use Case |
|---|---|---|---|---|
v0.24.0 | infiniflow/ragflow | ~2 GB | Stable | Production |
nightly | infiniflow/ragflow | ~2 GB | Unstable | Testing latest features |
Regional Mirror Repositories (China) docker/.env159-165:
swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflowinfiniflow-registry.cn-shanghai.cr.aliyuncs.com/infiniflow/ragflowHistorical Note: Prior to v0.22.0, RAGFlow shipped separate -slim images without embedding models. Starting v0.22.0, only slim editions are published README.md208-215
Text Embeddings Inference (TEI) docker/.env172-181:
Alternative Models:
BAAI/bge-m3: 21GB RAMBAAI/bge-small-en-v1.5: 1.2GB RAMSandbox Images docker/.env250-254:
Sources: docker/.env156-181 README.md208-215
The RAGFlow Docker image uses a three-stage build process to minimize final image size while including all necessary dependencies.
Stage 1: base Dockerfile1-145
infiniflow/ragflow_deps:latest:
/root/nltk_data/ragflow/rag/res/deepdoc/ragflow/tika-server-standard-3.2.3.jar/ragflow/9b5ad71b2ce5302211f9c61530b329a4922fc6a4/opt/chrome/usr/local/bin/chromedriverStage 2: builder Dockerfile147-180
uv sync --python 3.12 --frozen using pyproject.toml1-282npm install && npm run build in web/ directory/ragflow/VERSIONStage 3: production Dockerfile182-215
${VIRTUAL_ENV} → /ragflow/.venvweb/dist/ → /ragflow/web/dist/api/, rag/, agent/, deepdoc/, etc.docker/service_conf.yaml.template → conf/./entrypoint.shBuild Command with Mirrors README.md296-313:
When NEED_MIRROR=1:
Sources: Dockerfile1-215 README.md296-313
Entrypoint Script Dockerfile207-208:
The container executes ./entrypoint.sh which performs:
Service configuration generation: Substitutes environment variables into conf/service_conf.yaml.template to create the runtime configuration file
Database initialization:
rag_flow database if it doesn't existapi/db/init_data.pySuperuser creation (optional):
INIT_SUPERUSER_ARGS is set, creates admin account[email protected] --password=admin123 --nickname=AdminService startup:
api/ragflow_server.py: Main Quart API server (port 9380)rag/svr/task_executor.py: Document processing workernginx: Web server (ports 80/443)Sources: Dockerfile207-215 docker/service_conf.yaml.template1
The GitHub Actions workflow demonstrates advanced Docker Compose usage with dynamic port allocation for parallel test runners.
Dynamic Port Allocation .github/workflows/tests.yml156-198:
To support parallel runners, ports are computed based on runner number:
Configuration Patching:
Computed ports are appended to docker/.env .github/workflows/tests.yml180-202:
Coverage Collection:
The entrypoint is patched to run with coverage .github/workflows/tests.yml205-206:
Test Execution Pattern:
Tests wait for service availability before execution .github/workflows/tests.yml213-218:
Sources: .github/workflows/tests.yml140-287
1. "Can't connect to ES cluster" Exception
Cause: vm.max_map_count is below required value (262144).
Solution:
Make permanent by adding to /etc/sysctl.conf README.md158-178
2. Service Health Check Failures
Symptoms: Container repeatedly restarts or stays unhealthy.
Diagnosis:
Common causes:
MEM_LIMIT in .env)df -h)3. Frontend Shows "Network Abnormal"
Cause: Backend not fully initialized when accessing UI.
Solution: Wait for RAGFlow ASCII banner in logs README.md226-237:
4. ARM64 Platform Issues
Symptoms: Image pull fails or architecture mismatch errors.
Solution: Build custom image following Build System and CI/CD documentation README.md188-189:
5. Password Authentication Failures
Cause: Passwords in .env don't match those in service_conf.yaml.template.
Solution: Ensure consistency and restart services README.md259-260:
6. Volume Data Persistence Issues
Symptoms: Data lost after docker compose down.
Solution: Never use -v flag unless intentional data wipe docs/guides/upgrade_ragflow.mdx15:
Refresh this wiki