RAGFlow Provisioning Runbook

RAGFlow is provisioned per organization through the NestJS control plane. Keep RAGFLOW_PROVISIONING_MODE=manual until the shared Railway cluster, R2 credentials, and cross-org isolation eval have passed.

Do not commit Railway or Cloudflare tokens. Set them only in Railway environment variables 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 with an empty humanwork-ragflow-staging Railway project.
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 Railway cost dashboard 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:

RAGFLOW_PROVISIONING_MODE=manual

Manual mode records the desired service name, bucket, project id, and steps in organizations.metadata.ragflow_provisioning_state and returns instructions instead of calling Railway or Cloudflare.

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.