如何安装

sidebar_position: 2 title: Deploy Local Models sidebar_label: Deploy Local Models slug: /deploy_local_llm sidebar_custom_props: { categoryIcon: LucideMonitorCog }

Deploy Local Models

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Deploy and run local models using Ollama, Xinference, vLLM ，SGLang , GPUStack or other frameworks.

RAGFlow supports deploying models locally using Ollama, Xinference, IPEX-LLM, vLLM ，SGLang , GPUStack or jina. If you have locally deployed models to leverage or wish to enable GPU or CUDA for inference acceleration, you can bind Ollama or Xinference into RAGFlow and use either of them as a local "server" for interacting with your local models.

RAGFlow seamlessly integrates with Ollama and Xinference, without the need for further environment configurations. You can use them to deploy two types of local models in RAGFlow: chat models and embedding models.

:::tip NOTE This user guide does not intend to cover much of the installation or configuration details of Ollama or Xinference; its focus is on configurations inside RAGFlow. For the most current information, you may need to check out the official site of Ollama or Xinference. :::

Deploy Local Models Using Ollama

Ollama enables you to run open-source large language models that you deployed locally. It bundles model weights, configurations, and data into a single package, defined by a Modelfile, and optimizes setup and configurations, including GPU usage.

:::note - For information about downloading Ollama, see here. - For a complete list of supported models and variants, see the Ollama model library. :::

1. Deploy Ollama Using Docker

Ollama can be installed from binaries or deployed with Docker. Here are the instructions to deploy with Docker:

$ sudo docker run --name ollama -p 11434:11434 ollama/ollama
> time=2024-12-02T02:20:21.360Z level=INFO source=routes.go:1248 msg="Listening on [::]:11434 (version 0.4.6)"
> time=2024-12-02T02:20:21.360Z level=INFO source=common.go:49 msg="Dynamic LLM libraries" runners="[cpu cpu_avx cpu_avx2 cuda_v11 cuda_v12]"

Ensure Ollama is listening on all IP address:

$ sudo ss -tunlp | grep 11434
> tcp   LISTEN 0      4096                  0.0.0.0:11434      0.0.0.0:*    users:(("docker-proxy",pid=794507,fd=4))
> tcp   LISTEN 0      4096                     [::]:11434         [::]:*    users:(("docker-proxy",pid=794513,fd=4))

Pull models as you need. We recommend that you start with llama3.2 (a 3B chat model) and bge-m3 (a 567M embedding model):

$ sudo docker exec ollama ollama pull llama3.2
> pulling dde5aa3fc5ff... 100% ▕████████████████▏ 2.0 GB
> success

$ sudo docker exec ollama ollama pull bge-m3
> pulling daec91ffb5dd... 100% ▕████████████████▏ 1.2 GB
> success

2. Find Ollama URL and Ensure It Is Accessible

  • If RAGFlow runs in Docker, the localhost is mapped within the RAGFlow Docker container as host.docker.internal. If Ollama runs on the same host machine, the right URL to use for Ollama would be `http://host.docker.internal:11434/' and you should check that Ollama is accessible from inside the RAGFlow container with:
$ sudo docker exec -it docker-ragflow-cpu-1 bash
$ curl http://host.docker.internal:11434/
> Ollama is running
  • If RAGFlow is launched from source code and Ollama runs on the same host machine as RAGFlow, check if Ollama is accessible from RAGFlow's host machine:
$ curl http://localhost:11434/
> Ollama is running
  • If RAGFlow and Ollama run on different machines, check if Ollama is accessible from RAGFlow's host machine:
$ curl http://${IP_OF_OLLAMA_MACHINE}:11434/
> Ollama is running

3. Add Ollama

In RAGFlow, click on your logo on the top right of the page > Model providers and add Ollama to RAGFlow:

4. Complete Basic Ollama Settings

In the popup window, complete basic settings for Ollama:

  1. Ensure that your model name and type match those been pulled at step 1 (Deploy Ollama using Docker). For example, (llama3.2 and chat) or (bge-m3 and embedding).
  2. Put in the Ollama base URL, i.e. http://host.docker.internal:11434, http://localhost:11434 or http://${IP_OF_OLLAMA_MACHINE}:11434.
  3. OPTIONAL: Switch on the toggle under Does it support Vision? if your model includes an image-to-text model.

:::caution WARNING Improper base URL settings will trigger the following error:

Max retries exceeded with url: /api/chat (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0xffff98b81ff0>: Failed to establish a new connection: [Errno 111] Connection refused'))

:::

5. Update System Model Settings

Click on your logo > Model providers > System Model Settings to update your model:

  • You should now be able to find llama3.2 from the dropdown list under Chat model, and bge-m3 from the dropdown list under Embedding model.

6. Update Chat Configuration

Update your model(s) accordingly in Chat Configuration.

Deploy a Local Model Using Xinference

Xorbits Inference (Xinference) enables you to unleash the full potential of cutting-edge AI models.

:::note - For information about installing Xinference Ollama, see here. - For a complete list of supported models, see the Builtin Models. :::

To deploy a local model, e.g., Mistral, using Xinference:

1. Check Firewall Settings

Ensure that your host machine's firewall allows inbound connections on port 9997.

2. Start an Xinference Instance

$ xinference-local --host 0.0.0.0 --port 9997

3. Launch Your Local Model

Launch your local model (Mistral), ensuring that you replace ${quantization} with your chosen quantization method:

$ xinference launch -u mistral --model-name mistral-v0.1 --size-in-billions 7 --model-format pytorch --quantization ${quantization}

4. Add Xinference

In RAGFlow, click on your logo on the top right of the page > Model providers and add Xinference to RAGFlow:

5. Complete Basic Xinference Settings

Enter an accessible base URL, such as http://<your-xinference-endpoint-domain>:9997/v1.

For rerank model, please use the http://<your-xinference-endpoint-domain>:9997/v1/rerank as the base URL.

6. Update System Model Settings

Click on your logo > Model providers > System Model Settings to update your model.

You should now be able to find mistral from the dropdown list under Chat model.

7. Update Chat Configuration

Update your chat model accordingly in Chat Configuration:

Deploy a Local Model Using IPEX-LLM

IPEX-LLM is a PyTorch library for running LLMs on local Intel CPUs or GPUs (including iGPU or discrete GPUs like Arc, Flex, and Max) with low latency. It supports Ollama on Linux and Windows systems.

To deploy a local model, e.g., Qwen2, using IPEX-LLM-accelerated Ollama:

1. Check Firewall Settings

Ensure that your host machine's firewall allows inbound connections on port 11434. For example:

sudo ufw allow 11434/tcp

2. Launch Ollama Service Using IPEX-LLM

2.1 Install IPEX-LLM for Ollama

:::tip NOTE IPEX-LLM's supports Ollama on Linux and Windows systems. :::

For detailed information about installing IPEX-LLM for Ollama, see Run llama.cpp with IPEX-LLM on Intel GPU Guide: - Prerequisites - Install IPEX-LLM cpp with Ollama binaries

After the installation, you should have created a Conda environment, e.g., llm-cpp, for running Ollama commands with IPEX-LLM.

2.2 Initialize Ollama
  1. Activate the llm-cpp Conda environment and initialize Ollama:

<TabItem value="linux">

conda activate llm-cpp
init-ollama

</TabItem> <TabItem value="windows">

Run these commands with administrator privileges in Miniforge Prompt:

conda activate llm-cpp
init-ollama.bat

</TabItem>

  1. If the installed ipex-llm[cpp] requires an upgrade to the Ollama binary files, remove the old binary files and reinitialize Ollama using init-ollama (Linux) or init-ollama.bat (Windows).

A symbolic link to Ollama appears in your current directory, and you can use this executable file following standard Ollama commands.

2.3 Launch Ollama Service
  1. Set the environment variable OLLAMA_NUM_GPU to 999 to ensure that all layers of your model run on the Intel GPU; otherwise, some layers may default to CPU.
  2. For optimal performance on Intel Arc™ A-Series Graphics with Linux OS (Kernel 6.2), set the following environment variable before launching the Ollama service:
export SYCL_PI_LEVEL_ZERO_USE_IMMEDIATE_COMMANDLISTS=1
  1. Launch the Ollama service:

<TabItem value="linux">

export OLLAMA_NUM_GPU=999
export no_proxy=localhost,127.0.0.1
export ZES_ENABLE_SYSMAN=1
source /opt/intel/oneapi/setvars.sh
export SYCL_CACHE_PERSISTENT=1

./ollama serve

</TabItem> <TabItem value="windows">

Run the following command in Miniforge Prompt:

set OLLAMA_NUM_GPU=999
set no_proxy=localhost,127.0.0.1
set ZES_ENABLE_SYSMAN=1
set SYCL_CACHE_PERSISTENT=1

ollama serve

</TabItem>

:::tip NOTE To enable the Ollama service to accept connections from all IP addresses, use OLLAMA_HOST=0.0.0.0 ./ollama serve rather than simply ./ollama serve. :::

The console displays service startup messages.

3. Pull and Run Ollama Model

3.1 Pull Ollama Model

With the Ollama service running, open a new terminal and run ./ollama pull <model_name> (Linux) or ollama.exe pull <model_name> (Windows) to pull the desired model. e.g., qwen2:latest:

3.2 Run Ollama Model

<TabItem value="linux">

./ollama run qwen2:latest

</TabItem> <TabItem value="windows">

ollama run qwen2:latest

</TabItem>

4. Configure RAGFlow

To enable IPEX-LLM accelerated Ollama in RAGFlow, you must also complete the configurations in RAGFlow. The steps are identical to those outlined in the Deploy a local model using Ollama section:

  1. Add Ollama
  2. Complete basic Ollama settings
  3. Update System Model Settings
  4. Update Chat Configuration

5. Deploy vLLM

ubuntu 22.04/24.04

pip install vllm

5.1 Run vLLM with Best Practise

nohup vllm serve /data/Qwen3-8B --served-model-name Qwen3-8B-FP8 --dtype auto --port 1025 --gpu-memory-utilization 0.90 --tool-call-parser hermes --enable-auto-tool-choice  > /var/log/vllm_startup1.log 2>&1 &

you can get log info

tail -f -n 100 /var/log/vllm_startup1.log

when see the follow ,it means vllm engine is ready for access

Starting vLLM API server 0 on http://0.0.0.0:1025
Started server process [19177]
Application startup complete.

5.2 Integrating RAGFlow with vLLM Chat/Em/Rerank LLM with WebUI

Go to Settings → Model Providers → Search → vLLM → Add; configure as follows:

add vllm

Select the vLLM chat model as the default LLM model:

chat

5.3 Chat with vLLM Chat Model

Create a chat and start a conversation as follows:

chat

6. Deploy GPUStack

ubuntu 22.04/24.04

6.1 Run GPUStack with Best Practise

sudo docker run -d --name gpustack \
    --restart unless-stopped \
    -p 80:80 \
    -p 10161:10161 \
    --volume gpustack-data:/var/lib/gpustack \
    gpustack/gpustack

you can get docker info

docker ps

when see the follow ,it means vllm engine is ready for access

root@gpustack-prod:~# docker ps
CONTAINER ID   IMAGE               COMMAND                  CREATED       STATUS       PORTS                                                                                  NAMES
abf59be84b1a   gpustack/gpustack   "/usr/bin/entrypoint…"   6 hours ago   Up 6 hours   0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:10161->10161/tcp, [::]:10161->10161/tcp   gpustack

6.2 Integrating RAGFlow with GPUStack Chat/Em/Rerank LLM with WebUI

setting->model providers->search->gpustack->add ,configure as follow:

add vllm

Select the GPUStack chat model as the default LLM:

chat

sidebar_position: 3 title: Launch Service from Source sidebar_label: Launch Service from Source slug: /launch_ragflow_from_source sidebar_custom_props: { categoryIcon: LucideMonitorPlay }

Launch Service from Source

Build and run the complete Go API, admin, ingestor, and syncer services on your host, with supporting services in Docker. Run all commands from the repository root unless a step says otherwise. This guide uses the default Elasticsearch and MySQL configuration on Ubuntu 24.04 x86_64; the native ONNX Runtime archive used by this build targets Linux x86_64.

:::note macOS This source-build procedure is for Ubuntu 24.04 x86_64. On macOS, use Docker Desktop and follow Build RAGFlow Docker Image to build and run the Go linux/amd64 image. :::

The RAGFlow open-source 1.0 DeepDoc backend uses CPU inference for layout analysis, OCR, and table recognition.

All long-running RAGFlow processes started below use bin/ragflow_server.

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, data volume, parsing workload, and concurrency.
  • Docker 24.0.0 or later and Docker Compose v2.26.1 or later.
  • Go 1.27 or later, as declared in go.mod (check go version).
  • CMake 4.0 or later, Clang 20, LLD 20, and PCRE2 development headers.
  • Node.js 18.20.4 or later and npm for the frontend.
  • Python 3.10 or later only for ragflow_deps/download_deps.py, which downloads the native libraries and model resources required by the Go build.

See the Docker installation guide if Docker is not installed. Use the Go version declared in go.mod and the compiler versions listed above when preparing the build environment.

1. Get the source and build dependencies

git clone https://github.com/infiniflow/ragflow.git
cd ragflow
go version
cmake --version
clang++ --version
ld.lld --version

Install Go 1.27 or later if needed; make sure the Go executable selected by your shell meets the requirement in go.mod. On Ubuntu, install the compiler, linker, PCRE2 headers, Python virtual-environment support, and command-line tools used by the build with:

sudo apt update
sudo apt install -y clang-20 lld-20 libpcre2-dev python3-venv \
  build-essential binutils pkg-config curl ca-certificates

Ubuntu's enabled repositories may not provide clang-20 and lld-20. If APT cannot locate them, configure the official LLVM APT repository for LLVM 20, then run the installation command again. Follow the repository instructions at apt.llvm.org rather than substituting an older LLVM release.

Make clang++ resolve to Clang 20 and ld.lld to LLD 20 before building. Installing lld-20 alone does not necessarily replace an older system default ld.lld. Check both versions above: an older LLD can produce a binary that builds successfully but fails before the Go server starts. Install CMake 4.0 or later separately if your distribution package is older; the Go development guide includes the Ubuntu 24.04 Kitware repository setup. The binutils package supplies objcopy and nm; do not ignore a missing-objcopy warning because skipping the RE2 symbol-renaming step can cause a runtime crash.

Download the native libraries and Go DeepDoc model weights with a small, isolated Python environment:

python3 -m venv /tmp/ragflow-go-download-venv
/tmp/ragflow-go-download-venv/bin/python -m pip install requests huggingface-hub
/tmp/ragflow-go-download-venv/bin/python ragflow_deps/download_deps.py

The downloader fetches the static libraries needed by build.sh, plus det.ort, layout.ort, tsr.ort, rec.ort, and ocr.res into internal/rag/res/deepdoc/. These files are required by the in-process Go DeepDoc backend. Keep the server's working directory at the repository root so it can find them automatically; if you launch it elsewhere, set DEEPDOC_MODEL_DIR to the absolute path of internal/rag/res/deepdoc.

It also downloads ragflow_deps/cl100k_base.tiktoken and the embedding tokenizer assets, and installs the stagehand driver into ${XDG_CACHE_HOME:-$HOME/.cache}/stagehand/lib/go_<SDK version>/. Native archives support Linux x86_64.

The isolated download environment can be removed after the resources have been prepared.

Build the C++ bindings and Go binaries:

bash build.sh --all

For a smaller production binary, use bash build.sh --strip --all instead. The dependency downloader prepares ragflow_deps/cl100k_base.tiktoken. If the table is missing, download it before starting the server:

curl -fsSL -o ragflow_deps/cl100k_base.tiktoken https://openaipublic.blob.core.windows.net/encodings/cl100k_base.tiktoken

Check that the newly built executable can load and parse API arguments:

./bin/ragflow_server --api --help

It should print API usage information and may exit with status 1. This command only checks that the binary can load and parse arguments; it does not initialize DeepDoc, connect to dependencies, or prove that the API can start. Complete the runtime checks in section 5 after starting the dependencies and Go processes.

The Go/C++ build requires LLD 20. Confirm that ld.lld --version reports LLD 20 before building; merely installing lld-20 is insufficient when an older ld.lld remains the system default. If the binary builds successfully but exits or crashes before reaching Go main, verify the selected linker and rebuild with LLD 20.

To prepare the resource image used by the Go Dockerfile, run the downloader above, then build from ragflow_deps/:

cd ragflow_deps
docker build -f Dockerfile -t infiniflow/ragflow_deps:latest .
cd ..

The downloader prepares the five Go DeepDoc files under ragflow_deps/huggingface.co/InfiniFlow/deepdoc/ for the resource image, as well as internal/rag/res/deepdoc/ for local use. The Go Dockerfile copies these models into the runtime model directory. Analyzer dictionaries and fonts are installed separately by the Go Dockerfile.

2. Start supporting services

With the default conf/service_conf.yaml, the host-run Go processes need Elasticsearch, MySQL, MinIO, NATS, Kvrocks, and ClickHouse. Start these services explicitly from the repository root:

The default Elasticsearch service requires vm.max_map_count of at least 262144 on the Docker host. Check and set it before starting the containers:

sysctl vm.max_map_count
sudo sysctl -w vm.max_map_count=262144

The change made with sysctl -w is temporary. To preserve it after a reboot, add vm.max_map_count=262144 to /etc/sysctl.conf.

docker compose --env-file docker/.env -f docker/docker-compose-base.yml up -d --wait es01 mysql minio nats kvrocks clickhouse
docker compose --env-file docker/.env -f docker/docker-compose-base.yml ps

The base Compose file also defines an unprofiled Redis service. Starting every service with up -d can make Redis and Kvrocks compete for host port 6379; the explicit service list above starts Kvrocks for the Go backend. Compose may print a warning that REDIS_PORT is unset because the unused Redis service is still parsed.

Check that the services are ready before migrating. For this host-run setup, edit conf/service_conf.yaml if you changed the published ports or credentials in docker/.env. The defaults include MySQL at localhost:3306, Elasticsearch at localhost:1200, MinIO at localhost:9000, Kvrocks at localhost:6379, NATS at localhost:4222, and ClickHouse at localhost:9900. Do not edit docker/service_conf.yaml.template for a Go process launched directly on the host, and no /etc/hosts entries for Docker service names are needed.

3. Migrate and launch the Go backend

Run the migration once before starting any server process:

./bin/ragflow_server --migrate

Then start each Go mode in a separate terminal from the repository root. These four modes are the complete backend service chain. The source-development commands below use RAGFLOW_DEV_MODE=true to bypass the code and database version downgrade check; this setting does not run migrations or change the schema. Do not set it in production. Start Admin first so API, Ingestor, and Syncer can report their heartbeats:

# Terminal 1: admin (target port 9381)
RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin

# Terminal 2: API (target port 9380)
RAGFLOW_DEV_MODE=true ./bin/ragflow_server --api

# Terminal 3: document ingestion
RAGFLOW_DEV_MODE=true ./bin/ragflow_server --ingestor

Start the Go syncer in another terminal:

RAGFLOW_DEV_MODE=true ./bin/ragflow_server --syncer

After the migration completes, RAGFLOW_DEV_MODE=true bash build.sh --run can be used as a shortcut to start the Go Admin, Ingestor, and API modes. The shortcut does not start Syncer; run the Syncer command above separately when the complete service chain is required. It does not replace the standalone migration step.

If you changed a dependency's published port or credentials, update conf/service_conf.yaml before starting the Go processes. In particular, kvrocks.host is a single host:port value; the default source configuration is localhost:6379. Do not rely on KVROCKS_HOST and KVROCKS_PORT to override this source configuration.

RAGFLOW_DEV_MODE=true bypasses the code-versus-database version check. Use it only for development, not to run an older production binary against a newer database. The standalone --migrate action must still complete first.

If startup reports no in-process DeepDoc backend serving, check that all five model files above are in internal/rag/res/deepdoc/, then re-run the Go dependency downloader and rebuild if necessary. If the tokenizer reports a missing cl100k_base.tiktoken, ensure the BPE table is in ragflow_deps/.

4. Start the frontend

In another terminal:

cd web
npm install
API_PROXY_SCHEME=go npm run dev

With API_PROXY_SCHEME=go, the frontend routes requests to two Go backend ports: regular /api and /v1 requests use port 9380, while /api/v1/admin requests use port 9381. Open http://127.0.0.1:9222/ unless Vite prints a different frontend port.

5. Verify the startup

From a separate terminal, check the frontend, an API request through its Go proxy, and the ClickHouse HTTP health endpoint:

curl -fsS http://127.0.0.1:9380/api/v1/system/healthz
curl -fsS -o /dev/null -w 'frontend: HTTP %{http_code}\n' http://127.0.0.1:9222/
curl -fsS http://127.0.0.1:9222/api/v1/system/version
curl -fsS http://127.0.0.1:8123/ping

The direct Go API health check and frontend should return HTTP 200, the version request should return JSON with "code":0, and ClickHouse should respond Ok.. These runtime checks confirm that the Go API, frontend proxy, and ClickHouse are reachable; also confirm that the startup logs report the in-process DeepDoc backend as registered before testing your intended RAGFlow workflow.

6. Stop the services

Press Ctrl+C in the frontend and Go server terminals. To stop the dependency containers started in step 2:

docker compose --env-file docker/.env -f docker/docker-compose-base.yml stop \
  es01 mysql minio nats kvrocks clickhouse

stop preserves the dependency containers for the next development session. To remove the containers and Compose network while keeping named data volumes, use docker compose --env-file docker/.env -f docker/docker-compose-base.yml down.

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 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 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 .
  1. 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.

  1. 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.