Skip to main content

Build RAGFlow Docker Image

Build the Go backend and web frontend 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 the infiniflow/ragflow_deps:latest and infiniflow/github_action_runner:latest images during the build

The documented Go image target is linux/amd64. On an Apple Silicon Mac, Docker Desktop builds and runs this image through x86-64 emulation.

Platform support

  • Linux x86-64: This is the supported Docker build target. In the RAGFlow open-source 1.0 release, DeepDoc uses CPU inference for layout analysis, OCR, and table recognition.
  • Apple Silicon macOS: Build and run the linux/amd64 image through Docker Desktop x86-64 emulation. Document processing and image builds may be slower than on an x86-64 Linux host.
  • Linux ARM64: A native Go Docker build is not currently supported. The Go image depends on native libraries that are published for Linux x86-64. Use a Linux x86-64 host for a supported native build.
  • 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. For the Go deployment, change the corresponding values in docker/.env; use docker/.env only when a separate command explicitly loads that file.

Build the Go 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
docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local .

Dockerfile builds the Go server and web frontend. infiniflow/ragflow_deps:latest supplies document models and tokenizer assets; infiniflow/github_action_runner:latest supplies the build toolchain and prebuilt ONNX Runtime libraries. You do not need to build either dependency image separately for this command.

Start the service

For the default Elasticsearch document engine on Linux, set vm.max_map_count to at least 262144 on the Docker host. For macOS, use the Docker Desktop command below instead.

sudo sysctl -w vm.max_map_count=262144

Set RAGFLOW_IMAGE=ragflow:go-local in docker/.env. That file also controls the document engine, CPU or GPU selection, 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. The open-source 1.0 Go DeepDoc backend uses CPU inference.

Verify the service

docker compose -f docker-compose.yml ps
docker compose -f docker-compose.yml logs --tail 50 ragflow-cpu
curl -f http://localhost/api/v1/system/healthz

A healthy API returns HTTP 200. If you changed SVR_WEB_HTTP_PORT in .env, use that port in the health-check URL and when opening the web interface in a browser.

For a development checkout, a database version error may require RAGFLOW_DEV_MODE=true in .env. Use this only for local development; keep it false for production.

macOS with Docker Desktop

The same Go image and Compose file work on macOS. On Apple Silicon, keep --platform linux/amd64 in the build command so that the x86-64 Go image and native libraries use the same architecture. Emulation can make the build and document processing slower than on an x86-64 Linux host.

  1. Start Docker Desktop and build from the repository root:

    git clone https://github.com/infiniflow/ragflow.git
    cd ragflow
    docker build --platform linux/amd64 -f Dockerfile -t ragflow:go-local .

  2. If you use the default Elasticsearch document engine, set vm.max_map_count inside Docker Desktop's Linux virtual machine:

    docker run --rm --privileged alpine sysctl -w vm.max_map_count=262144

    Repeat this command after restarting Docker Desktop. It is unnecessary when using another document engine such as Infinity.

  3. Set RAGFLOW_IMAGE=ragflow:go-local in docker/.env, then start the Go stack:

    cd docker
    docker compose -f docker-compose.yml up -d
    curl -f http://localhost/api/v1/system/healthz

    Wait for the health check to return HTTP 200, then open http://localhost in a browser. Include SVR_WEB_HTTP_PORT in both URLs if you changed its default value.