ragflow/docs/develop/launch_ragflow_from_source.md

---
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. macOS is temporarily not supported by the Go backend, so use a Linux x86_64 host to build and run the Go services.
:::

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 for `tools/scripts/download_dev_deps.py` and `deps/download_deps.py`, which download the native libraries and model resources required by the Go build.

See the [Docker installation guide](https://docs.docker.com/engine/install/) 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

```bash
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`. Install `uv` as well; the dependency downloaders run through it. On Ubuntu, install the compiler, linker, PCRE2 headers, Python 3, and command-line tools used by the build with:

```bash
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](https://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 static libraries and the runtime model / tokenizer resources with the two dependency downloaders (`uv run` installs each script's declared Python dependencies):

```bash
uv run tools/scripts/download_dev_deps.py   # local-dev one-stop: native .a + cl100k, DeepDoc .ort, tokenizer assets
```

`download_dev_deps.py` is the local-dev one-stop: it fetches the static libraries needed by `build.sh` (pdfium / pdf_oxide / office_oxide / onnxruntime → `~/ragflow-native-libs`) AND the runtime resources the backend loads at runtime — `det.ort`, `layout.ort`, `tsr.ort`, `rec.ort`, `ocr.res` into `internal/rag/res/deepdoc/` (required by the in-process Go DeepDoc backend) and `deps/cl100k_base.tiktoken` and the embedding tokenizer assets under `deps/huggingface.co/`. Run it once and the local environment is ready; already-present files are skipped on re-run. The image-facing `deps/download_deps.py` fetches the same runtime resources PLUS the stagehand server (installed into `${XDG_CACHE_HOME:-$HOME/.cache}/stagehand/lib/go_<SDK version>/`) and skips the native `.a`; run it only when building the dependency image or in CI. Native archives support Linux x86_64. Keep the server's working directory at the repository root so it can find the DeepDoc models automatically; if you launch it elsewhere, set `DEEPDOC_MODEL_DIR` to the absolute path of `internal/rag/res/deepdoc`.

Skip either script if you have prepared the same resources by other means.

Build the C++ bindings and Go binaries:

```bash
bash build.sh --all
```

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

```bash
curl -fsSL -o 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:

```bash
./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, first run `uv run deps/download_deps.py` (above) to populate `deps/`, then build from `deps/`:

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

The downloader prepares the five Go DeepDoc files under `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:

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

```bash
docker compose --env-file docker/.env -f docker/docker-compose-base.yml up -d --wait es01 mysql minio nats kvrocks clickhouse
docker 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:

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

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

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

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

Start the Go syncer in another terminal:

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

## 4. Start the frontend

In another terminal:

```bash
cd web
npm install
npm run dev
```

The frontend routes requests to the Go backend by default: 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:

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

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