快速开始（1/2）

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: 2 slug: / sidebar_custom_props: { sidebarIcon: LucideRocket }

RAGFlow is an open-source RAG (Retrieval-Augmented Generation) engine based on deep document understanding. When integrated with LLMs, it is capable of providing truthful question-answering capabilities, backed by well-founded citations from various complex formatted data.

This quick start guide describes a general process from:

  • Starting up a local RAGFlow server,
  • Creating a dataset,
  • Establishing an AI chat based on your datasets.

:::danger IMPORTANT This guide deploys the Go backend with the repository's Go Docker image and Compose configuration. The supported native Docker build target is Linux x86-64. Linux ARM64 is not currently a supported native target because the Go image depends on native libraries published for x86-64. :::

Prerequisites

  • A recommended starting configuration of 4 CPU cores (x86-64), 16 GB RAM, and 50 GB free disk space. Actual requirements depend on the document engine, data volume, parsing workload, and concurrency. Local models and OceanBase require additional resources.
  • Docker ≥ 24.0.0 with Docker Compose ≥ v2.26.1 and BuildKit;
  • Access to the dependency image infiniflow/ragflow_deps:latest during the image build, and to an LLM and embedding model at runtime.

If Docker is not installed, see Install Docker Engine.

Start up the server

  1. For the default Elasticsearch document engine, ensure vm.max_map_count is at least 262144 on the Docker host:
sysctl vm.max_map_count
sudo sysctl -w vm.max_map_count=262144

The change made with sysctl -w is temporary. To keep it after a reboot, set vm.max_map_count=262144 in /etc/sysctl.conf. On Docker Desktop, apply the setting to its Linux VM.

  1. Clone the repository:
git clone https://github.com/infiniflow/ragflow.git
  1. Check out the Go release tag and start the prebuilt Go image with Docker Compose:
# Enter the Docker deployment directory.
cd ragflow/docker
# Check out the Go v1.0.0-rc1 release tag.
git checkout v1.0.0-rc1
# Start the Go services and their dependencies in the background.
docker compose -f docker-compose.yml up -d

The docker/.env file controls DOC_ENGINE, service ports, and dependency credentials. Change the default passwords before deploying to a network-accessible host.

In the RAGFlow open-source 1.0 release, DeepDoc layout analysis, OCR, and table recognition use CPU inference.

:::caution Development checkouts A development checkout can report a code version older than the database migration version, including immediately after its own migrations. In that case, the Go server refuses to start with Refusing to start: database was migrated by a newer version. For local development with this checkout, set RAGFLOW_DEV_MODE=true in .env and run the Compose command again. This disables the database downgrade check; leave RAGFLOW_DEV_MODE=false for production, and use a binary whose version is at least the database migration version. :::

  1. Check that the service is running:
docker compose -f docker-compose.yml ps
docker logs -f ragflow-cpu

After initialization, check the Go API and its dependencies through the web port from another terminal:

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

A successful response has HTTP status 200. If you changed SVR_WEB_HTTP_PORT in .env, include that port in the URL. Wait for this check to pass before opening the web interface.

  1. Open http://IP_OF_YOUR_MACHINE in a browser and log in. If you changed SVR_WEB_HTTP_PORT in .env, include that port in the URL.

The Go container runs the API server, ingestion workers, and data synchronization. Its startup script runs the Go database migrations before starting the services.

Configure LLMs

RAGFlow is a RAG engine and needs to work with an LLM to offer grounded, hallucination-free question-answering capabilities. RAGFlow supports most mainstream LLMs. For a complete list of supported models, please refer to Supported Models.

:::note RAGFlow also supports deploying LLMs locally using Ollama, Xinference, or LocalAI, but this part is not covered in this quick start guide. :::

To add and configure an LLM:

  1. Click on your logo on the top right of the page > Model providers.

  2. Click on the desired LLM and update the API key accordingly.

  3. Click Set default models to select the default models:

  4. Chat model,

  5. Embedding model,
  6. Image-to-text model,
  7. and more.

Some models, such as the image-to-text model qwen-vl-max, are subsidiary to a specific LLM. And you may need to update your API key to access these models.

Create your first dataset

You can upload files to a dataset in RAGFlow and parse them into chunks. A dataset is a collection of documents. Question answering in RAGFlow can be based on one or more datasets. Supported file formats include documents (PDF, DOC, DOCX, TXT, MD, MDX), tables (CSV, XLSX, XLS), images (JPEG, JPG, PNG, TIF, GIF), and slides (PPT, PPTX).

To create your first dataset:

  1. Click the Dataset tab in the top middle of the page > Create dataset.

  2. Input the name of your dataset and click OK to confirm your changes.

You are taken to the Configuration page of your dataset.

dataset configuration

  1. RAGFlow offers multiple chunk templates that cater to different document layouts and file formats. Select the embedding model and chunking method (template) for your dataset.

:::danger IMPORTANT Once you have selected an embedding model and used it to parse a file, you are no longer allowed to change it. The obvious reason is that we must ensure that all files in a specific dataset are parsed using the same embedding model (ensure that they are being compared in the same embedding space). :::

You are taken to the Dataset page of your dataset.

  1. Click + Add file > Local files to start uploading a particular file to the dataset.

  2. In the uploaded file entry, click the play button to start file parsing:

parse file

If parsing stalls, check the ragflow-cpu service logs with the Compose command above for ingestion errors.

Intervene with file parsing

RAGFlow features visibility and explainability, allowing you to view the chunking results and intervene where necessary. To do so:

  1. Click on the file that completes file parsing to view the chunking results:

You are taken to the Chunk page:

chunks

  1. Hover over each snapshot for a quick view of each chunk.

  2. Double click the chunked texts to add keywords or make manual changes where necessary:

update chunk

:::caution NOTE You can add keywords or questions to a file chunk to improve its ranking for queries containing those keywords. This action increases its keyword weight and can improve its position in search list. :::

  1. In Retrieval testing, ask a quick question in Test text to double check if your configurations work:

As you can tell from the following, RAGFlow responds with truthful citations.

retrieval test

Set up an AI chat

Conversations in RAGFlow are based on a particular dataset or multiple datasets. Once you have created your dataset and finished file parsing, you can go ahead and start an AI conversation.

  1. Click the Chat tab in the middle top of the page > Create chat to create a chat assistant.

  2. Click the created chat app to enter its configuration page.

    RAGFlow lets you choose a chat model for each dialogue. You can configure the defaults under Set default models.

  3. Update Chat setting on the right of the configuration page:

  4. Name your assistant and specify your datasets.

  5. Empty response:

    • If you wish to confine RAGFlow's answers to your datasets, leave a response here. Then when it doesn't retrieve an answer, it uniformly responds with what you set here.
    • If you wish RAGFlow to improvise when it doesn't retrieve an answer from your datasets, leave it blank, which may give rise to hallucinations.

  6. Update System prompt or leave it as is for the beginning.

  7. Select a chat model in the Model dropdown list.

  8. Now, let's start the show:

chat_thermal_solution

:::tip NOTE RAGFlow also offers an HTTP API for integrating its capabilities into your applications:

sidebar_position: 2 title: Sandbox Quickstart sidebar_label: Sandbox Quickstart slug: /sandbox_quickstart sidebar_custom_props: { categoryIcon: LucideCog }

Sandbox quickstart

RAGFlow's CodeExec agent component needs a sandbox provider to run Python and JavaScript code.

The simplest setup flow is:

  1. Start the required sandbox services.
  2. Open the RAGFlow admin page.
  3. Go to Admin > Sandbox Settings.
  4. Choose a provider and save the configuration.
  5. Test the connection in the same page.

Admin page

Configure sandbox providers from the admin page:

  • self_managed: Uses the executor manager service.
  • ssh: Runs code on a remote machine over SSH.
  • aliyun_codeinterpreter, e2b, and tenki: Cloud providers.

Provider options

RAGFlow supports multiple sandbox providers. Configure the active provider in Admin > Sandbox Settings after the services are up.

  • self_managed: Runs code inside Docker-managed sandbox containers. This is the default provider.
  • ssh: Runs code on a remote machine over SSH.
  • aliyun_codeinterpreter and e2b: Cloud-hosted providers that remain available in the admin provider list.
  • tenki: Cloud-hosted provider that runs each execution in a disposable Tenki microVM. See Tenki below.

Tenki

tenki runs each code execution in a fresh Tenki microVM and destroys it afterward. It is cloud-hosted, so it needs no local sandbox services, gVisor, or Docker base images — only outbound network access and an API key.

Configure it in Admin > Sandbox Settings:

  • api_key (required): Tenki API key. Create one at app.tenki.cloud under API Keys.
  • project_id (required): the Tenki project that sandboxes are created under.
  • base_url (optional): override the Tenki API endpoint.
  • image (optional): sandbox base image. Leave empty to use the Tenki default image, which includes python3 and node.
  • allow_outbound (optional, security-relevant): whether the sandbox may make outbound network connections. Defaults to false so sandboxed code has no network access; set it to true when code needs the network (for example, to install packages).
  • timeout, max_lifetime, cpu_cores, memory_mb, disk_size_gb, and the output/artifact limits have sensible defaults and can be tuned in the same page.

Notes:

  • Supported languages are Python and JavaScript.
  • Files written to the artifacts/ directory of the working directory are returned as run artifacts.
  • The provider uses only Tenki's create/exec/destroy operations; it does not use volumes or snapshots.

Self-Managed prerequisites

The following prerequisites apply only when you use the self_managed provider:

  • Linux distribution compatible with gVisor.
  • gVisor installed and configured.
  • Docker version 25.0 or higher (API 1.44+). Ensure your executor manager image ships with Docker CLI 29.1.0 or higher to stay compatible with the latest Docker daemons.
  • Docker Compose version 2.26.1 or higher (similar to RAGFlow requirements).
  • uv package and project manager installed.
  • (Optional) GNU Make for simplified command-line management.

:::tip NOTE The error message client version 1.43 is too old. Minimum supported API version is 1.44 indicates that your executor manager image's built-in Docker CLI version is lower than 29.1.0 required by the Docker daemon in use. :::

Build Docker base images

The sandbox uses isolated base images for secure containerized execution environments.

Option 1: Build from source

Build the runtime base images:

docker build -t sandbox-base-python:latest ./sandbox_base_image/python
docker build -t sandbox-base-nodejs:latest ./sandbox_base_image/nodejs

Alternatively, build all base images at once using the Makefile:

make build

Build the executor manager image:

docker build -t sandbox-executor-manager:latest ./executor_manager

Option 2: Pull base images from Docker Hub

If you do not need to customize runtime dependencies, pull the published base images and tag them with the names used by standalone Docker Compose:

docker pull infiniflow/sandbox-base-python:latest
docker pull infiniflow/sandbox-base-nodejs:latest

docker tag infiniflow/sandbox-base-python:latest sandbox-base-python:latest
docker tag infiniflow/sandbox-base-nodejs:latest sandbox-base-nodejs:latest

Then restart the standalone sandbox services:

# Stop the standalone Sandbox services before applying the changes.
docker compose -f docker-compose.yml down
# Start the standalone Sandbox services in the background.
docker compose -f docker-compose.yml up -d

Running with RAGFlow

  1. If you use the self_managed provider, verify that gVisor is installed and operational.

  2. Configure docker/.env:

  3. Include sandbox in COMPOSE_PROFILES if you want the default self_managed executor-manager service.

  4. If you use the ssh provider, set RAGFLOW_SSH_KNOWN_HOSTS to the host known_hosts file and keep SSH_KNOWN_HOSTS as the path used inside the Go container. The default values are ${HOME}/.ssh/known_hosts and /etc/ragflow/ssh_known_hosts.

  5. Keep the self-managed deployment defaults in .env if you need to change the sandbox-executor-manager image, pool size, base images, seccomp, memory, or timeout.

  6. Add the following entry to your /etc/hosts file to resolve the executor manager service:

127.0.0.1 es01 infinity mysql minio kvrocks sandbox-executor-manager
  1. Start the RAGFlow service as usual.
  2. Open Admin > Sandbox Settings.
  3. Select a provider.
  4. Fill in the required fields.
  5. Click Save.
  6. Click Test Connection if needed.

Environment variables

The variables in docker/.env are grouped by scope.

System-level variables

These variables apply to the sandbox deployment:

  • COMPOSE_PROFILES: Include sandbox to start the default self-managed executor-manager service.
  • SANDBOX_ARTIFACT_BUCKET: MinIO bucket used for files generated by sandbox code.

Self-managed deployment defaults

These variables are shown in Admin as deployment defaults for self_managed. Changing them requires restarting sandbox-executor-manager.

  • SANDBOX_EXECUTOR_MANAGER_IMAGE: Docker image for the executor manager service. Defaults to infiniflow/sandbox-executor-manager:latest.
  • SANDBOX_EXECUTOR_MANAGER_POOL_SIZE: Number of Python and Node.js sandbox containers kept in each runtime pool. Defaults to 3.
  • SANDBOX_BASE_PYTHON_IMAGE: Python runtime image used by executor-managed containers. Defaults to infiniflow/sandbox-base-python:latest.
  • SANDBOX_BASE_NODEJS_IMAGE: Node.js runtime image used by executor-managed containers. Defaults to infiniflow/sandbox-base-nodejs:latest.
  • SANDBOX_EXECUTOR_MANAGER_PORT: Host port exposed by the executor manager. Defaults to 9385 and binds to 127.0.0.1 in the provided Compose configuration.
  • SANDBOX_ENABLE_SECCOMP: Enables the optional seccomp profile for sandbox containers. Defaults to false.
  • SANDBOX_MAX_MEMORY: Memory limit for each sandbox runtime container. Defaults to 256m; it is not the total memory limit for all sandbox containers.
  • SANDBOX_CONTAINER_NETWORK: Docker network attached to each sandbox runtime container. Defaults to none, which prevents external network access. Use bridge only when sandboxed code needs outbound network access.
  • SANDBOX_TIMEOUT: Default execution timeout. Defaults to 10s.
  • SANDBOX_EXECUTOR_MANAGER_API_TOKEN: Shared secret used to authenticate requests from RAGFlow to the executor manager. Set a strong value for network-accessible deployments; the same value is passed to both services by the provided Compose configuration.

Admin-managed runtime settings

Provider selection and runtime settings are configured in Admin > Sandbox Settings.

Examples:

  • Choose the active provider
  • Configure self_managed runtime settings
  • Configure all ssh settings

For self_managed:

  • Runtime settings are editable in Admin
  • Deployment defaults come from .env and are shown as read-only values

Running standalone

Manual setup

  1. Initialize the environment variables:
cp .env.example .env
  1. Launch the sandbox services with Docker Compose:
docker compose -f docker-compose.yml up
  1. Test the sandbox setup:
source .venv/bin/activate
export PYTHONPATH=$(pwd)
uv pip install -r executor_manager/requirements.txt
uv run tests/sandbox_security_tests_full.py

Using Makefile

Run all setup, build, launch, and tests with a single command:

make

Monitoring

To follow logs of the executor manager container:

docker logs -f sandbox-executor-manager

Or use the Makefile shortcut:

make logs

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.