ragflow/docs/develop/build_docker_image.mdx

---
sidebar_position: 4
title: Build RAGFlow Docker Image
sidebar_label: Build RAGFlow Docker Image
slug: /build_docker_image
sidebar_custom_props: {
  categoryIcon: LucidePackage
}
---

# 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-rc2. To deploy a published image, follow the [Quickstart](../quickstart.mdx). 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.

```bash
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.

```bash
git clone https://github.com/infiniflow/ragflow.git
cd ragflow
git checkout v1.0.0-rc2
```

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:

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

On a Linux ARM64 host:

```bash
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.

```bash
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:

```bash
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.

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

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

```bash
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:

```bash
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](https://ragflow.io/docs/dev/llm_api_key_setup) for details.

## Docker configuration and adjustment

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