Clarify backend root URL requirements#75
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates documentation to clarify that OpenBB Workspace integrations must be configured with a backend root base URL and that widgets.json must be served from <base-url>/widgets.json, addressing LAN and reverse-proxy/prefix deployment confusion from #31.
Changes:
- Add “Backend URL requirements” guidance to the root
README.md, including LAN (--host 0.0.0.0) and prefix-routing notes. - Add “Connecting from OpenBB Workspace” guidance to the reference backend README with supported/unsupported URL examples.
- Fix formatting of the “Examples of apps” link in the root README.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| README.md | Adds root-URL + widgets.json expectations and deployment notes; fixes a formatting issue in the examples link. |
| getting-started/reference-backend/README.md | Adds explicit connection guidance for Workspace with examples and deployment/prefix notes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <base-url>/widgets.json | ||
| ``` | ||
|
|
||
| That means the backend configuration must be served from the root of the backend base URL. |
There was a problem hiding this comment.
The sentence "the backend configuration must be served from the root" is ambiguous and can be read as requiring all backend routes to be rooted at , which conflicts with the next paragraph that allows prefixed routes. Consider rephrasing to explicitly state that only widgets.json must be available at <base-url>/widgets.json (and that other endpoints may live under a prefix).
| That means the backend configuration must be served from the root of the backend base URL. | |
| That means only `widgets.json` must be served from the root of the backend base URL at `<base-url>/widgets.json`; other backend endpoints may still live under a prefix. |
There was a problem hiding this comment.
apps.json / widgets.json - any config really - we dont want to say just widgets.json
| uvicorn main:app --host 0.0.0.0 --port 7777 | ||
| ``` | ||
|
|
||
| If you need to serve additional application routes under a prefix such as `/vstock`, keep `widgets.json` at the backend root and put the rest of your routes behind the prefix. If your deployment requires a path prefix for the entire backend, use a dedicated host or subdomain instead of a subpath. |
There was a problem hiding this comment.
This paragraph suggests serving application routes under a prefix while keeping widgets.json at the root, but it doesn’t mention that widget endpoint values in widgets.json must include that prefix (e.g., vstock/...) for OpenBB Workspace to call the correct URLs. Adding that detail would prevent misconfiguration when users mount all API routes under a path prefix.
| If you need to serve additional application routes under a prefix such as `/vstock`, keep `widgets.json` at the backend root and put the rest of your routes behind the prefix. If your deployment requires a path prefix for the entire backend, use a dedicated host or subdomain instead of a subpath. | |
| If you need to serve additional application routes under a prefix such as `/vstock`, keep `widgets.json` at the backend root and put the rest of your routes behind the prefix. In that setup, the widget `endpoint` values in `widgets.json` must also include the prefix (for example, `vstock/...`) so OpenBB Workspace calls the correct URLs. If your deployment requires a path prefix for the entire backend, use a dedicated host or subdomain instead of a subpath. |
|
|
||
| OpenBB Workspace expects `widgets.json` to be available at `<base-url>/widgets.json`. | ||
|
|
||
| If you need to expose other endpoints under a prefix, keep `widgets.json` at the root and mount your application routes separately. For LAN deployments, run uvicorn with `--host 0.0.0.0` so the backend is reachable from other machines. |
There was a problem hiding this comment.
When advising users to put endpoints behind a prefix, it would help to explicitly note that the endpoint fields in widgets.json need to include that prefix so Workspace requests resolve correctly (since Workspace builds URLs from the base URL + endpoint).
| If you need to expose other endpoints under a prefix, keep `widgets.json` at the root and mount your application routes separately. For LAN deployments, run uvicorn with `--host 0.0.0.0` so the backend is reachable from other machines. | |
| If you need to expose other endpoints under a prefix, keep `widgets.json` at the root and mount your application routes separately. In that setup, the `endpoint` fields in `widgets.json` must include the same prefix (for example, `/api/widget-name` rather than `/widget-name`), because Workspace builds request URLs from the base URL plus each widget `endpoint`. For LAN deployments, run uvicorn with `--host 0.0.0.0` so the backend is reachable from other machines. |
|
these are nice things to add - i would just clarify what you have on the first suggestion |
Summary
widgets.jsonat<base-url>/widgets.json/vstock--host 0.0.0.0) and prefix-based routing while keepingwidgets.jsonat the rootCloses #31
Testing
git diff --check