Superseded by haystack-deploy.md

RAGFlow Provisioning Runbook

Status (2026-06-02): RAGFlow is provisioned per-org against a single shared RAGFlow instance per environment. The instance itself currently runs on Railway; migration to a single AWS-hosted instance (serving dev/staging/prod under separate Lago-style env partitioning) is in flight with no committed date. The correction→KB refinement processor is live (PR #303). ADR-009 collapsed the per-tenant Railway-service design into a shared-instance + tenant_id design; RAGFLOW_PROVISIONING_MODE is no longer used. Several P0/P1 follow-up issues remain open — see Open Issues at the bottom.

RAGFlow is provisioned per organization through the NestJS control plane against a single shared RAGFlow instance (one per environment), using RAGFlow's native tenant_id boundary for multi-tenant isolation. See ADR-009 for the rationale.

Do not commit hosting-provider or Cloudflare tokens. Set them only in the environment-variable surface of the active host (Railway today; AWS once migrated) or local shell for one-off ops.

Backfill

Dry-run first:

api/scripts/ragflow-backfill.ts --dry-run

Execute one batch, capped at 5 orgs by default:

api/scripts/ragflow-backfill.ts

Bulk override requires the explicit flag:

api/scripts/ragflow-backfill.ts --allow-bulk

The script filters active orgs only: active, pending_client_confirmation, pending_specialist_assignment, trial_ending. It skips orgs that already have IntegrationCredential.integrationType='ragflow' and tracks progress in organizations.metadata.ragflow_backfill_status.

Recommended Sequence

1. Deploy RF-0003 to staging against the shared RAGFlow staging instance (Railway today; AWS once migrated).
2. Backfill staging orgs: dry-run, verify estimated cost, execute, then smoke-test upload and retrieval.
3. Run the cross-org isolation eval before provisioning any production tenant.
4. Deploy to production.
5. Backfill production in batches of 5 with a manual gate between batches. Watch the active host's cost dashboard (Railway today; AWS billing once migrated) and cluster health between batches.

Manual Escape Hatches

SuperAdmin one-off provision:

POST /ops/orgs/:id/ragflow-provision

In production, pass confirmProduction=true.

Kill switch (manual mode):

# Unset RAGFLOW_DEFAULT_BASE_URL

When RAGFLOW_DEFAULT_BASE_URL is unset, provisionForOrg falls back to manual mode: records the desired service name, bucket, project id, and steps in organizations.metadata.ragflow_provisioning_state and returns instructions instead of calling RAGFlow.

Local mock mode:

RAGFLOW_DEFAULT_BASE_URL=http://localhost:9380

When set, provisioning skips Railway/Cloudflare and creates a local ragflow integration credential using the default dataset ids.

Recovery Notes

If provisioning stops halfway, inspect:

SELECT id, name, metadata->'ragflow_provisioning_state'
FROM organizations
WHERE metadata ? 'ragflow_provisioning_state';

Re-running the backfill is idempotent for completed orgs because it skips orgs with an existing ragflow integration credential. For manual-mode orgs, complete the listed external steps, then store the encrypted credential through the credentials API or a controlled migration.

---

Open Issues (as of 2026-06-01)

#	Title	Priority
#315	RAGFlow org-member sync — mirror Humanwork memberships into RAGFlow tenant	P0
#296	Onboarding: business-context upload step	P2

Recently Resolved

PR / Issue	What
#723	ADR-009 shared-instance + tenant_id disposition — closes #291, #298, #299, #300, #315*, #317 (2026-05-26). (#315 reopened scoped to membership sync only.)
#297	Client KB management UI — closed 2026-05-26 via the KB UI workstream (#817 / #818 / #819 / #823).
#303	Correction → KB refinement processor + corrections dataset (live)
#324	Multiple RAGFlow stability fixes: LLM categorization shape validation, cold-start Redis, streaming try/finally, etc.
Various	RAGFlow retrieval response unwrapping, admin DI, public key override, dashboard login recovery, backfill guard