[Kubernetes Deployment] Configure Web Base Path via Environment Variable

[McFredward]

What problem are you trying to solve?

When Open Design is deployed behind a reverse proxy or ingress under a sub-path like /opendesign, the application still generates some URLs as if it were hosted at /. This causes broken navigation, asset loading, and plugin preview requests unless the app is served from the root path.
We need a supported way to configure the web base path for example through an environment variable, like OD_WEB_BASE_PATH=/opendesign.

Why this is needed

• Community-Clusters in my company share the same base URL, so it's impossible to deploy directly on /. Changing it to a subpath is a requirement for me.
• Some routes, assets, and preview/plugin URLs currently miss the base path prefix
• This leads to broken reloads, wrong browser URLs, and missing assets in production deployments

Describe the solution you'd like

What should change

• Introduce one official env var for the web base path, e.g. OD_WEB_BASE_PATH
• Ensure all browser-visible routes respect that base path
• Ensure all frontend-generated asset URLs respect that base path
• Ensure all browser-side /api/... calls respect that base path
• Ensure plugin preview/example HTML and related asset URLs also work correctly behind the configured base path
• Document the variable for Docker/Kubernetes deployments

Acceptance criteria

• With OD_WEB_BASE_PATH=/opendesign, the app works fully under /opendesign
• Browser navigation uses /opendesign/...
• Refreshing deep links works
• Static assets load from /opendesign/...
• Browser API calls go to /opendesign/api/...
• Plugin preview/example assets also load correctly behind the same prefix

I have already started changing most places, so the basic functionality of OpenDesign is now working under a subpath—just so you can see a possible way to implement this (not final):

https://github.com/nexu-io/open-design/compare/release/v0.8.0...McFredward:open-design:feature/base-path-full?expand=1

Alternatives you've considered

There are no alternatives I'm aware of—just path-rewrite in the ingress is not enough, since all API calls in the web application are using the base path.

Additional context

No response

Would you be willing to contribute a PR?

Yes, with guidance from a maintainer

[open-design-bot]

🎉 ✨ Welcome to Open Design, @McFredward!

✨ 🔥 Lit the spark.

🌱 Every contribution adds energy to the project. Thanks for showing up and helping Open Design grow.

💛 Thanks for helping Open Design grow. Keep building in the open. 🚀

🔗 Share on X (English) · 分享到 X（中文）

[lefarcen]

Hi @McFredward! 👋 The sub-path deployment scenario you've described is a real constraint for shared-cluster setups, and the acceptance criteria you've laid out — browser nav, deep link refreshes, static assets, /api/… calls, and plugin preview assets all respecting the configured prefix — give us a clear picture of the scope involved.

I've routed this to @elihahah666 (our product lead) to assess roadmap fit before we confirm a direction for contributors. You should hear back within around 12 hours.

Your draft branch (feature/base-path-full) is a helpful reference — it's on the record for when review begins.

[McFredward]

Hi @McFredward! 👋 The sub-path deployment scenario you've described is a real constraint for shared-cluster setups, and the acceptance criteria you've laid out — browser nav, deep link refreshes, static assets, /api/… calls, and plugin preview assets all respecting the configured prefix — give us a clear picture of the scope involved.

I've routed this to @elihahah666 (our product lead) to assess roadmap fit before we confirm a direction for contributors. You should hear back within around 12 hours.

Your draft branch (feature/base-path-full) is a helpful reference — it's on the record for when review begins.

Any updates on this? I’m still waiting for this feature, as otherwise I always need to rebuild a large section of the code to deploy it. I assume I’m not the only one with a shared cluster setup facing this issue.

[lefarcen]

Hey @McFredward — I checked the current code and the related deployment thread, and there is a more concrete update now.

This is already being tracked in #2895. That thread has the earlier direction for a fixed static base path, plus a maintainer implementation outline covering the same surfaces you're hitting: router paths, /api/*, /artifacts/*, /frames/*, /_next/*, and OAuth callback URLs. In the code today, OD_PUBLIC_BASE_URL only feeds the OAuth callback base in apps/daemon/src/server.ts; it does not yet prefix general browser routes or frontend /api calls, so your shared-cluster ingress case still needs real base-path support rather than a simple rewrite.

To avoid splitting review across two issues, let’s consolidate on #2895 from here. Your report is still useful signal — it confirms this is not a one-off deployment edge case. If you want to help implement it, please comment there (or open a PR that references both issues) so the existing design discussion and any in-flight work stay in one place. There's already an active technical thread there from @evanzmz as well.

[lefarcen]

Hey @McFredward — one more concrete follow-up here so this thread doesn’t just sit waiting.

The active implementation path is still #2895, and that thread already has the agreed scope plus maintainer guidance for the fixed static base-path approach. If you want to push this forward from your feature/base-path-full branch, please open a PR and reference both #2895 and #3302 — that will put the review back onto the current implementation track instead of splitting discussion across two issue threads.

Your deployment case is still valid signal for us; the main thing now is to move the code discussion / PR onto #2895 where the scoping notes already live.

[github-actions]

This issue has been inactive for 30 days and is being marked as stale. If it is still relevant, please leave a comment or push an update — otherwise it will be closed in 7 days.

This is only a queue-management step, not a rejection of the report. Closed issues can be reopened when work resumes.

[lefarcen]

PR #5567 is wiring fixed OD_WEB_BASE_PATH support through the self-hosted deployment path end-to-end — Web asset/link resolution, prefixed API/SSE and preview/artifact routes, plus reverse-proxy X-Forwarded-Prefix validation.

Keeping this issue open until the draft lands and the prefixed deployment path is verified on merge.

[lefarcen]

Hey @McFredward — there is a concrete update now.

The implementation is in PR #5567, which carries the fixed OD_WEB_BASE_PATH support through the self-hosted deployment path. At the moment that PR is still open and not merge-ready yet: the current review state is changes requested, so the ball is with the author to address the remaining review feedback on the latest head.

So this request is no longer just sitting in backlog — it has an active implementation track. Once PR #5567 clears review, we can move it through the remaining merge/QA steps from there.

[lefarcen]

Hey @McFredward — another concrete update here.

PR #5567 has now cleared the blocking code-review pass on its current head: @mrcfps approved commit 0f7e6d8a on July 14, 2026. So this is no longer sitting in the "changes requested" state from the last issue-side update.

It still is not shipped yet, though. PR #5567 remains open and still has remaining merge / validation steps before it can land, so we're keeping this issue open until that path is fully merged and the prefixed self-hosted deployment flow is verified.