ragflow-runbook

What this skill does

# ragflow-runbook Skill

A practical runbook for deploying, operating, troubleshooting, and calling RAGFlow (Retrieval-Augmented Generation).

Goal: any agent should be able to bring RAGFlow up, diagnose failures, and call the API safely even without knowing the deployment details up front.

---

## 1) When To Use

- Deploy RAGFlow (Docker / Windows / Linux / WSL2).
- Troubleshoot failures: startup issues, unhealthy backend services, port conflicts, performance problems.
- Use the API for operations purposes: validate liveness/readiness, verify auth, and check system endpoints.
- Run health checks, automate smoke tests, or prepare backup/restore.

## 2) What The Agent Must Ask First (Minimum Inputs)

Before running any commands, confirm the following (missing any of these often leads to wrong assumptions):

- Deployment environment: `Windows / WSL2 / Linux / macOS (client only)`
- Install directory (the directory that contains `docker-compose.yml`)
- Access method:
  - `RAGFLOW_BASE_URL` (e.g. `http://localhost:9380` or an internal/Tailscale address)
  - Whether there is an Nginx/reverse proxy in front (and whether Web UI uses port 80/8080)
- Whether an API key already exists (do NOT paste secrets into chat; use env vars / secret manager)
- Current symptom:
  - "does not start" vs "starts but UI/API errors" vs "retrieval quality is poor"

> Security: never store or share API keys / DB passwords in plaintext (docs, repo, or chat).

---

## 3) Canonical Environment Variables (Recommended)

Use environment variables so all agents can run the same commands:

- `RAGFLOW_BASE_URL`: prefer an internal/Tailscale URL, e.g. `http://100.x.y.z:9380`
- `RAGFLOW_API_KEY`: Bearer token (created in the RAGFlow Web UI)

Quick verification (separate liveness / readiness / auth; tolerate path differences across versions):

- Liveness (usually no auth; try in order, any 200 is OK):
  - `GET $RAGFLOW_BASE_URL/openapi.json`
  - `GET $RAGFLOW_BASE_URL/api/v1/openapi.json`
  - `GET $RAGFLOW_BASE_URL/v1/system/ping`
- Readiness (often requires auth; try in order):
  - `GET $RAGFLOW_BASE_URL/v1/system/status`
  - `GET $RAGFLOW_BASE_URL/v1/system/ping`

If these do not match your deployment: treat the returned `openapi.json` as the source of truth.

This skill ships with its own ops helpers under `scripts/`:

- `scripts/ragflow_ping.py`: liveness + readiness
- `scripts/ragflow_smoke.py`: auth + API smoke (system-level only)
- `scripts/ragflow_status.py`: compact status summary
- `scripts/ragflow_alert.py`: send an ops alert via OpenClaw messaging

This skill is intentionally decoupled from any workspace-specific application content. It focuses only on RAGFlow runtime operations.

---

## 4) Bootstrap (Fresh Install; Windows/WSL2 + Linux)

This section targets a brand-new machine. Goal: get to a working UI + API quickly:
clone upstream docker bundle -> start -> create API key in UI -> validate via curl/scripts.

### 4.1 Choose Install Mode (Default)

- Primary path (best for most desktop / Windows users): Windows + WSL2
- Alternate path: a Linux server (Ubuntu/Debian/CentOS/etc.)

### 4.1.1 Fresh Install: Copy/Paste (WSL2 / Linux)

WSL2 (recommended: store files on a Windows drive like `D:`; run commands inside WSL2):

```bash
# WSL2
cd /mnt/d

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

# Common requirement for some document engine profiles
sudo sysctl -w vm.max_map_count=262144 || true

# Default .env = elasticsearch + cpu
# To change ports/passwords/image versions: edit docker/.env

docker compose up -d

docker compose ps
```

Linux:

```bash
# Linux
sudo mkdir -p /opt && cd /opt
sudo chown -R "$USER" /opt

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

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

docker compose up -d

docker compose ps
```

Next: open Web UI (default `http://<host>:80`), finish initialization, create an API key, then validate using `## 3` + `## 8`.

### 4.2 Get The Official Docker Compose Bundle (Robust; Verified Against Upstream)

To avoid missing files or mismatched versions, use `git clone` and run from the upstream `docker/` directory:

```bash
git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker

# Optional: pin to a tag/commit for production
# git checkout <tag-or-commit>
```

The upstream `docker/` folder typically includes:

- `docker-compose.yml` (often `include: ./docker-compose-base.yml`)
- `docker-compose-base.yml` (backend services: database + cache + object storage + document engine)
- `.env` (default ports/passwords; change for production)
- `service_conf.yaml.template` (used to generate `service_conf.yaml` at container startup)
- `entrypoint.sh` (commonly started with flags like `--enable-adminserver` / `--enable-mcpserver`)
- `nginx/` (for built-in Web UI / reverse proxy)
- `README.md` (docker-specific docs)

Note: upstream explicitly warns that some compose variants (e.g. `docker-compose-macos.yml`) are not actively maintained. Do not use them unless you know why.

### 4.3 First Bring-Up (Upstream `COMPOSE_PROFILES`)

Upstream `.env` defaults:

- `COMPOSE_PROFILES` is derived from selected backend profiles (e.g. document engine + compute device)

So you typically do not need to pass `--profile` manually. `docker compose up -d` will pick profiles from `.env`.

Before starting (Linux/WSL2, for some document engine profiles):

```bash
cat /proc/sys/vm/max_map_count || true
sudo sysctl -w vm.max_map_count=262144 || true
```

Start:

```bash
# In ragflow/docker
# Optional: explicit profiles if you do not want to rely on COMPOSE_PROFILES
# docker compose --profile elasticsearch --profile cpu up -d

docker compose up -d

docker compose ps
```

Switch CPU/GPU (examples):

```bash
# Option 1: edit docker/.env
# DEVICE=gpu

# Option 2: override temporarily (do not modify files)
DEVICE=gpu docker compose up -d
```

Enable embeddings service (TEI): upstream suggests adding a tei profile to `COMPOSE_PROFILES`:

```bash
# Example:
# COMPOSE_PROFILES=${COMPOSE_PROFILES},tei-cpu
# or:
# COMPOSE_PROFILES=${COMPOSE_PROFILES},tei-gpu

docker compose up -d
```

Validation: wait for key services to be running/healthy in `docker compose ps`, then run liveness/readiness (## 3) and API prefix detection (## 8).

### 4.4 First-Time Setup Checklist (Aligned With Upstream `.env`)

In upstream `docker/.env` (main branch), exposed ports typically mean:

- Web UI / WebServer: `SVR_WEB_HTTP_PORT` (default 80), `SVR_WEB_HTTPS_PORT` (default 443)
- API (RAGFlow HTTP): `SVR_HTTP_PORT` (default 9380)
- Admin Server: `ADMIN_SVR_HTTP_PORT` (default 9381)
- MCP: `SVR_MCP_PORT` (default 9382)

Shortest path to a usable setup:

1) Open Web UI: `http://<host>:${SVR_WEB_HTTP_PORT}` (default `http://<host>:80`)
2) Complete initialization (admin/org setup depending on version)
3) Create an API key (usually under Settings/System/API Keys)
4) Set on the client side (recommended env vars):

- `RAGFLOW_BASE_URL=http://<host>:${SVR_HTTP_PORT}` (default `http://<host>:9380`)
- `RAGFLOW_API_KEY=ragflow-...` (Bearer token; do not paste secrets into chat)

Then validate with liveness/readiness in `## 3`.

> Production warning: upstream `.env` explicitly warns against using default passwords. At minimum change `ELASTIC_PASSWORD`, `MYSQL_PASSWORD`, `MINIO_PASSWORD`, and `REDIS_PASSWORD`.

---

## 5) Quick Start (Ops Checklist)

### 5.1 Prerequisites

- Docker Engine + Docker Compose v2 (`docker compose ...`)
- Resources (rule of thumb):
  - CPU >= 4 cores, RAM >= 16GB (32GB recommended)
  - Disk >= 50GB (depends on document volume + vector index size)
- Linux/WSL2: `vm.max_map_count >= 262144` (required by some document engine profiles)

Checks:

```bash
docker --version
docker compose version

# Linux/WSL2 only
cat /proc/sys/vm/max_map_count
```

Temporary fix (Linux/WSL2):

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

### 5.2 Bring-Up (Docker Compose)

Prereq: you are in the directory that contains `docker-compos