Ragflow RunbookCAUTION

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

# Prepare files (git clone path may still run; starting containers is disabled by default)
bash skills/ragflow-runbook/scripts/deploy.sh /opt/ragflow

# Explicitly allow starting containers
RAGFLOW_RUNBOOK_ALLOW_START=1 bash skills/ragflow-runbook/scripts/deploy.sh /opt/ragflow

# If git is not available and you want to allow runtime downloads
RAGFLOW_RUNBOOK_ALLOW_DOWNLOAD=1 RAGFLOW_RUNBOOK_ALLOW_START=1 bash skills/ragflow-runbook/scripts/deploy.sh /opt/ragflow

export RAGFLOW_BASE_URL="http://127.0.0.1:9380"
export RAGFLOW_API_KEY="ragflow-..."  # do not paste into chat / do not commit

python3 skills/ragflow-runbook/scripts/ragflow_ping.py
python3 skills/ragflow-runbook/scripts/ragflow_smoke.py
bash skills/ragflow-runbook/scripts/healthcheck.sh

ragflow-runbook/
├── SKILL.md              # Full runbook (ops playbook)
├── README.md             # This file
├── CHANGELOG.md
├── package.json
├── scripts/
│   ├── deploy.sh         # Deploy helper (git clone preferred)
│   ├── healthcheck.sh    # Healthcheck wrapper (calls skill-local scripts)
│   ├── ragflow_ping.py   # Liveness + readiness
│   ├── ragflow_smoke.py  # Ops smoke (

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: ragflow-runbook
version: 0.1.4
description: End-to-end runbook for deploying, operating, troubleshooting, and monitoring RAGFlow (runtime ops only).

# Compatibility: some registries/security scanners only detect env vars if they are declared
# at the document top-level or under `metadata.env`. We keep the OpenClaw namespace too.
env:
  required: [RAGFLOW_BASE_URL]
  optional: [RAGFLOW_API_KEY, OPENCLAW_PRIMARY_CHAT_ID]

metadata:
  env:
    required: [RAGFLOW_BASE_URL]
    optional: [RAGFLOW_API_KEY, OPENCLAW_PRIMARY_CHAT_ID]
  openclaw:
    requires:
      bins: [python3, docker, curl]
      optional_bins: [git, openclaw]
    env:
      required: [RAGFLOW_BASE_URL]
      optional: [RAGFLOW_API_KEY, OPENCLAW_PRIMARY_CHAT_ID]
---

# 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 

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

declared (6 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (6)

*/10 * * * * RAGFLOW_BASE_URL="http://127.0.0.1:9380" RAGFLOW_API_KEY="${RAGFLOW_API_KEY}" /usr/bin/python3 /path/to/skills/ragflow-runbook/scripts/ragflow_ping.py || /usr/bin/python3 /path/to/skills/

5 6 * * * RAGFLOW_BASE_URL="http://127.0.0.1:9380" RAGFLOW_API_KEY="${RAGFLOW_API_KEY}" /usr/bin/python3 /path/to/skills/ragflow-runbook/scripts/ragflow_smoke.py || /usr/bin/python3 /path/to/skills/ra

<string>http://127.0.0.1:9380</string>

<string>http://127.0.0.1:9380</string>

<key>k5Ey9KFlkqpj+SDkUw+5ED9lTA3En/qUi0zdrydUCH3kMWTE3Eh65NXnFCaxlY2omY2JHnlEoK7Li7oOEvM7eG5VPdcO/sFlMfoCRdnLYdepJ+uLzYwOWR8W4yQVve/clxVFTVRL4DFleKInGdpAxIbHZT2yi4ADAMENls1N1XSLojRuqXePXDeAT/4Mv4TTx0s

export RAGFLOW_BASE_URL="http://127.0.0.1:9380"

Gates applied: no_behavioural_pass.