Launch Service from Source

A guide explaining how to set up a RAGFlow service from its source code. By following this guide, you'll be able to debug using the source code.

Target Audience

Developers who have added new features or modified existing code and wish to debug using the source code, provided that their machine has the target deployment environment set up.

Prerequisites

CPU ≥ 4 cores
RAM ≥ 16 GB
Disk ≥ 50 GB
Docker ≥ 24.0.0 & Docker Compose ≥ v2.26.1

NOTE

If you have not installed Docker on your local machine (Windows, Mac, or Linux), see the Install Docker Engine guide.

Launch a Service from Source

To launch a RAGFlow service from source code:

Clone the RAGFlow Repository

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/

Install Python Dependencies

Install uv:
```
pipx install uv
```
Install RAGFlow service's Python dependencies:
```
uv sync --python 3.13 --frozen
```
A virtual environment named .venv is created, and all Python dependencies are installed into the new environment.

If you need to run tests against the RAGFlow service, install the test dependencies:
```
uv sync --python 3.13 --group test --frozen && uv pip install sdk/python --group test
```

macOS

On macOS, some Python dependencies link against native libraries that are not installed by default. Install them with Homebrew before launching the backend service:

brew install unixodbc jemalloc pkg-config

unixodbc provides libodbc.2.dylib, which the pyodbc package links against. Without it, import pyodbc fails with Library not loaded: .../libodbc.2.dylib (the full path is $(brew --prefix unixodbc)/lib/libodbc.2.dylib; /opt/homebrew on Apple Silicon, /usr/local on Intel), and the ExeSQL agent tool fails to load (look for Warning: Failed to import module exesql at startup).
jemalloc and pkg-config are required by the preload commands used to launch the task executor; see step 5 of Launch the RAGFlow Backend Service.

Launch Third-Party Services

The following command launches the 'base' services (MinIO, Elasticsearch, Redis, and MySQL) using Docker Compose:

docker compose -f docker/docker-compose-base.yml up -d

Update `host` and `port` Settings for Third-Party Services

Add the following line to /etc/hosts to resolve all hosts specified in docker/service_conf.yaml.template to 127.0.0.1:
```
127.0.0.1       es01 infinity mysql minio redis
```
In docker/service_conf.yaml.template, update mysql port to 5455 and es port to 1200, as specified in docker/.env.

Launch the RAGFlow Backend Service

Comment out the nginx line in docker/entrypoint.sh.
```
# /usr/sbin/nginx
```

Activate the Python virtual environment:

source .venv/bin/activate
export PYTHONPATH=$(pwd)

Optional: If you cannot access HuggingFace, set the HF_ENDPOINT environment variable to use a mirror site:
```
export HF_ENDPOINT=https://hf-mirror.com
```
Check the configuration in conf/service_conf.yaml, ensuring all hosts and ports are correctly set.

Run the entrypoint.sh script to launch the backend service:

JEMALLOC_PATH=$(pkg-config --variable=libdir jemalloc)/libjemalloc.so;
LD_PRELOAD=$JEMALLOC_PATH python rag/svr/task_executor.py -i 1;

On macOS, use the Homebrew dylib and DYLD_INSERT_LIBRARIES instead:

JEMALLOC_PATH=$(pkg-config --variable=libdir jemalloc)/libjemalloc.2.dylib;
DYLD_INSERT_LIBRARIES=$JEMALLOC_PATH python rag/svr/task_executor.py -i 1;

python api/ragflow_server.py;

Launch the RAGFlow Frontend Service

Navigate to the web directory and install the frontend dependencies:
```
cd web
npm install
```
Start the RAGFlow frontend service with the proxy configured for the Python backend:
```
API_PROXY_SCHEME=python npm run dev
```
The python proxy scheme routes API requests to the Python backend on port 9380. Use go for the Go backend on port 9384, or hybrid when running both backends.

The following message appears, showing the IP address and port number of your frontend service:

Access the RAGFlow Service

In your web browser, enter http://127.0.0.1:<PORT>/, ensuring the port number matches that shown in the screenshot above.

Stop the RAGFlow Service When the Development Is Done

Stop the RAGFlow frontend service:
```
pkill npm
```
Stop the RAGFlow backend service:
```
pkill -f "docker/entrypoint.sh"
```