Skip to main content

Build RAGFlow Docker Image

Build RAGFlow from source into a local Docker image for development and testing. The image uses external LLM and embedding services at runtime.

Prerequisites

  • A recommended starting configuration of 4 CPU cores, 16 GB RAM, and 50 GB free disk space. Actual requirements depend on the selected document engine, local models, build concurrency, and data volume.
  • Docker ≥ 24.0.0 with Docker Compose ≥ v2.26.1 and BuildKit.
  • Access to infiniflow/ragflow_deps:latest and the build image for your target architecture: infiniflow/github_action_runner:latest for x86-64 or infiniflow/github_action_runner:latest-arm64 for ARM64.
  • Internet access during the build to download system packages, fonts, tokenizer resources, npm dependencies, and Go modules. Pulling the dependency images in advance is not sufficient for an offline build.

RAGFlow provides prebuilt Docker images for Linux x86-64 and ARM64 starting with v1.0.0-rc3. To deploy a published image, follow the Quickstart. The instructions below cover building a Docker image from source on a Linux host matching the target architecture.

For the default Elasticsearch document engine on Linux, set vm.max_map_count to at least 262144 on the Docker host.

sysctl vm.max_map_count
# Run this only if the current value is below 262144.
sudo sysctl -w vm.max_map_count=262144

This change is temporary. To preserve it after a reboot, add or update vm.max_map_count=262144 in /etc/sysctl.conf. This step is usually unnecessary with Infinity.

Platform support

  • Linux x86-64: Native Docker builds targeting linux/amd64 are supported. In the RAGFlow open-source 1.0 release, DeepDoc uses CPU inference for layout analysis, OCR, and table recognition.
  • macOS: macOS is not currently supported by the Go backend. Use a Linux host for this workflow.
  • Linux ARM64: Native Docker builds targeting linux/arm64 are supported. Build on a Linux ARM64 host using the ARM64 build image and native dependencies.
  • Document engines: Elasticsearch is the default engine in the Compose example. Infinity and other supported engines may have different CPU, GPU, and architecture requirements; verify the selected engine before deployment.

Before starting the stack, make sure the host ports used by the selected Compose profile are available. At minimum, check the web, metadata database, cache, object storage, and NATS monitoring ports. Change the corresponding host-published port values in docker/.env. The startup commands below run from docker/, where Compose automatically reads .env; the RAGFlow service also loads it through env_file.

Build the RAGFlow Docker image

Run the build from the repository root. Keep the .git directory in the build context: Dockerfile uses it to stamp the image version.

git clone https://github.com/infiniflow/ragflow.git
cd ragflow
git checkout v1.0.0-rc3

Use the same release tag as the README deployment instructions so the image and local Compose files match. For development, check out the branch or commit you intend to test instead, and keep its Docker deployment files with the built image.

On a Linux x86-64 host:

docker build --platform linux/amd64 -f Dockerfile -t ragflow:local .

On a Linux ARM64 host:

docker build --platform linux/arm64 -f Dockerfile -t ragflow:local .

Dockerfile builds the RAGFlow server and web frontend. infiniflow/ragflow_deps:latest supplies document models and tokenizer assets. The build stages use infiniflow/github_action_runner:latest for x86-64 or infiniflow/github_action_runner:latest-arm64 for ARM64 to provide the toolchain and native dependencies, including ONNX Runtime libraries. These images must be accessible during the build; you do not need to build them separately.

Start the service

Set RAGFLOW_IMAGE=ragflow:local in docker/.env and keep DEVICE=cpu for this deployment. The Compose file defines the RAGFlow service under the cpu profile; setting DEVICE=gpu does not start that service. The .env file also controls the document engine, ports, and dependency credentials. Change the default passwords before making the service accessible over a network.

cd docker
docker compose -f docker-compose.yml up -d

The Compose deployment starts the ragflow-cpu service and its selected dependencies. With the default MySQL configuration, the image entrypoint runs database migrations before starting Admin, Syncer, Ingestor, API, and other services. The open-source 1.0 Go DeepDoc backend uses CPU inference.

Verify the service

Run the following commands from docker/. Check the dependency services first:

docker ps

After the dependencies show healthy and the RAGFlow container remains running, check the HTTP endpoint. The RAGFlow container itself does not define a Compose healthcheck.

curl -f http://localhost/api/v1/system/healthz

If initialization is still in progress, wait and retry. If startup fails, inspect the service logs:

docker logs --tail 50 ragflow-cpu

If startup is blocked because a development branch reports a code version older than the database migration version, consider setting RAGFLOW_DEV_MODE=true in .env for local development only. Keep it false for production. After changing .env, apply the setting by running:

docker compose -f docker-compose.yml up -d

After receiving HTTP 200, open http://IP_OF_YOUR_MACHINE in a browser and log in. If you changed SVR_WEB_HTTP_PORT in .env, use that port in both the health-check URL and the web interface URL.

After signing in, add an LLM, embedding, and reranker on the model provider page, including the model name, service address, and API key. See Configure model API keys for details.

Docker configuration and adjustment

Docker deployment uses docker/.env and docker/docker-compose.yml. See the Docker configuration guide for configuring the RAGFlow image, ports, passwords, document engine, and embedding service image, as well as restarting services and retaining or removing existing data.