feat(api): connect to an external Ray cluster via RAY_ADDRESS

[Ahmath-Gadji]

What

Make ray.init() in openrag/api.py branch on RAY_ADDRESS:

• RAY_ADDRESS set → ray.init(address=...) to attach to an external Ray cluster (e.g. a dedicated ray-head container / KubeRay). No embedded dashboard is started — the head node owns it.
• unset → embedded mode as before, binding the unauthenticated dashboard to 127.0.0.1 by default (CVE-2023-48022), overridable via RAY_DASHBOARD_HOST.

_ray_address = os.environ.get("RAY_ADDRESS")
if _ray_address:
    # Connect to an external Ray cluster (e.g. a dedicated ray-head container).
    ray.init(address=_ray_address)
else:
    # Embedded mode: start a local Ray cluster inside this process.
    ray.init(dashboard_host=os.environ.get("RAY_DASHBOARD_HOST", "127.0.0.1"))

Why

RAY_ADDRESS was already referenced in the cluster-deployment docs and relied on Ray implicitly reading the env var, while the code unconditionally passed dashboard_host (meaningless when attaching to an existing cluster). This makes the two modes explicit and keeps the secure-by-default dashboard binding for embedded runs.

Docs / env

• .env.example, docs/assets/env_example.env, docs/assets/env_linux_gpu.env — document RAY_ADDRESS and RAY_DASHBOARD_HOST (both commented out).
• docs/content/docs/documentation/env_vars.md — new rows for RAY_ADDRESS and RAY_DASHBOARD_HOST.
• docs/content/docs/documentation/deploy_ray_cluster.md — note clarifying that in attach mode the head node owns the dashboard.

Notes

• No docker-compose changes: the dashboard-host default on main is already 127.0.0.1; this PR is scoped to the RAY_ADDRESS attach path + docs.
• ruff check openrag/api.py passes.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added support for connecting to an external Ray cluster using RAY_ADDRESS, with embedded mode used only when it’s unset.
  • Improved embedded Ray dashboard configuration via RAY_DASHBOARD_HOST (defaulting to loopback).

• Documentation

  • Updated environment examples and Ray documentation to reflect external cluster attachment behavior and dashboard ownership.
  • Added security guidance around the embedded Ray dashboard/job-submission API and recommended exposure controls.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9b281684-36a5-4f6e-ab8a-ac094c799141

📥 Commits

Reviewing files that changed from the base of the PR and between 48928d1 and aa015bd.

📒 Files selected for processing (6)

• .env.example
• docs/assets/env_example.env
• docs/assets/env_linux_gpu.env
• docs/content/docs/documentation/deploy_ray_cluster.md
• docs/content/docs/documentation/env_vars.md
• openrag/api.py

✅ Files skipped from review due to trivial changes (5)

• .env.example
• docs/assets/env_linux_gpu.env
• docs/content/docs/documentation/deploy_ray_cluster.md
• docs/content/docs/documentation/env_vars.md
• docs/assets/env_example.env

🚧 Files skipped from review as they are similar to previous changes (1)

• openrag/api.py

---

📝 Walkthrough

Walkthrough

Adds conditional Ray initialization to openrag/api.py: when RAY_ADDRESS is set the app connects to an external Ray cluster; otherwise it starts an embedded cluster with RAY_DASHBOARD_HOST (default 127.0.0.1). Matching comments and documentation are added to three env example files, the env-vars reference table, and the deploy-Ray-cluster guide.

Changes

External Ray Cluster Support

Layer / File(s)	Summary
Conditional Ray initialization openrag/api.py	Replaces unconditional embedded ray.init with a branch on RAY_ADDRESS: connects to an external cluster when the variable is set, otherwise starts embedded Ray with dashboard_host read from RAY_DASHBOARD_HOST (defaulting to 127.0.0.1).
Env files and documentation .env.example, docs/assets/env_example.env, docs/assets/env_linux_gpu.env, docs/content/docs/documentation/env_vars.md, docs/content/docs/documentation/deploy_ray_cluster.md	Adds commented RAY_ADDRESS and RAY_DASHBOARD_HOST entries to all env example files, registers both variables in the env-vars reference table, and inserts a :::note block in the Ray cluster deployment guide explaining embedded vs. external dashboard ownership and the CVE-2023-48022 security context.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐇 A hop to the cluster, far away it may be,
Set RAY_ADDRESS and connect with glee!
The dashboard stays bound to loopback, secure and tight,
CVE noted — we keep our APIs right.
Two env vars documented, the path is now clear,
External Ray clusters? Bring them right here! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding support for connecting to an external Ray cluster via RAY_ADDRESS.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/ray-external-cluster-address

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[hedhoud]

One small docs concern: this note makes the app-side behavior clear, but the security warning should also cover the Ray head dashboard. In cluster mode, that head dashboard is the one users will actually have running, and the example starts it on all interfaces. If the port is not kept private, firewalled, or placed behind auth, users can still end up exposing Ray's unauthenticated dashboard/job API.

[hedhoud]

This should probably call out the Ray head dashboard too. In cluster mode the app does not start its own dashboard, but the example above starts the head dashboard on all interfaces. If that port is not private, firewalled, or behind auth, users can still expose Ray's unauthenticated dashboard/job API.