From 8719dfd922f876754cad3c24433089d9c2796fe9 Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 8 Oct 2026 10:15:15 +0200 Subject: [PATCH 01/13] feat(helm): support custom URL prefixes in microservices UI --- helm/litellm/README.md | 67 +++++++++++++++ helm/litellm/templates/_helpers.tpl | 8 ++ .../litellm/templates/backend/deployment.yaml | 5 ++ .../litellm/templates/gateway/deployment.yaml | 5 ++ helm/litellm/templates/ingress.yaml | 21 +++-- helm/litellm/templates/ui/deployment.yaml | 5 ++ .../litellm/tests/server_root_path_tests.yaml | 73 ++++++++++++++++ helm/litellm/values.yaml | 4 +- .../test_ui_root_path.py | 86 +++++++++++++++++++ ui/Dockerfile | 5 ++ ui/docker-entrypoint.sh | 12 +++ .../src/app/login/LoginPage.test.tsx | 12 ++- .../src/app/login/LoginPage.tsx | 7 +- .../src/lib/serverRootPath.test.tsx | 22 +++++ .../src/lib/serverRootPath.ts | 5 +- .../src/utils/returnUrlUtils.test.ts | 14 +++ .../src/utils/returnUrlUtils.ts | 5 +- ui/prepare-root-path.sh | 58 +++++++++++++ 18 files changed, 398 insertions(+), 16 deletions(-) create mode 100644 helm/litellm/README.md create mode 100644 helm/litellm/tests/server_root_path_tests.yaml create mode 100644 tests/proxy_migration_tests/test_ui_root_path.py create mode 100644 ui/docker-entrypoint.sh create mode 100644 ui/litellm-dashboard/src/lib/serverRootPath.test.tsx create mode 100644 ui/prepare-root-path.sh diff --git a/helm/litellm/README.md b/helm/litellm/README.md new file mode 100644 index 00000000000..b3c3080d076 --- /dev/null +++ b/helm/litellm/README.md @@ -0,0 +1,67 @@ +# Custom URL prefix + +Set `serverRootPath` to serve the componentized chart under a URL prefix. An empty value or `/` keeps the existing root deployment. A trailing slash is normalized + +```yaml +fullnameOverride: litellm +serverRootPath: /services/llm +ingress: + enabled: false +gateway: + extraEnv: + - name: PROXY_BASE_URL + value: https://platform.example.com/services/llm +backend: + extraEnv: + - name: PROXY_BASE_URL + value: https://platform.example.com/services/llm +``` + +Supply the chart's existing database, Redis, master-key and SSO settings as usual. Configure the OAuth callback as `https://platform.example.com/services/llm/sso/callback` + +The chart passes `SERVER_ROOT_PATH` to gateway, backend and UI. The UI image prepares its export in a fresh directory under `/tmp` at startup, leaving the packaged files untouched. With a read-only root filesystem, mount a writable `emptyDir` on `/tmp`. The default root deployment does not copy or rewrite the export + +When the chart's ingress is enabled, its built-in routes and `ingress.extraPaths` are prefixed. Paths in `extraPaths` remain root-relative, for example `/custom-provider`, and the chart adds the configured prefix. The ingress must preserve the path sent upstream. Prefixes containing dots require Gateway API or the ALB controller; ingress-nginx cannot preserve all of the chart's exact matches with its dotted-path normalization + +With an external Gateway API controller, route UI requests to port 3000, inference requests to port 4000, and management/configuration/SSO to port 4001. Preserve the prefix for Python services. The UI accepts both a preserved prefix and a prefix stripped by `URLRewrite` + +This Istio example covers the UI, configuration/SSO, chat completions and model listing. Add other inference routes from `templates/ingress.yaml` as needed. Do not send all `/v1` paths to the gateway: several management endpoints also use that version prefix + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: litellm + namespace: litellm +spec: + parentRefs: + - name: platform + namespace: istio-ingress + hostnames: + - platform.example.com + rules: + - matches: + - path: {type: Exact, value: /services/llm} + - path: {type: Exact, value: /services/llm/} + - path: {type: Exact, value: /services/llm/favicon.ico} + - path: {type: PathPrefix, value: /services/llm/ui} + - path: {type: PathPrefix, value: /services/llm/_next} + - path: {type: RegularExpression, value: '^/services/llm/.*\.txt$'} + backendRefs: + - name: litellm-ui + port: 3000 + - matches: + - path: {type: PathPrefix, value: /services/llm/v1/chat} + - path: {type: PathPrefix, value: /services/llm/chat} + - path: {type: PathPrefix, value: /services/llm/v1/models} + backendRefs: + - name: litellm-gateway + port: 4000 + - matches: + - path: {type: PathPrefix, value: /services/llm} + backendRefs: + - name: litellm-backend + port: 4001 +``` + +Health probes keep their existing unprefixed paths on the container port. Runtime prefix preparation changes static asset URLs and configuration discovery, and adds HTML metadata so the UI knows its prefix before hydration; login return URLs and dashboard navigation use the prefix reported by the backend diff --git a/helm/litellm/templates/_helpers.tpl b/helm/litellm/templates/_helpers.tpl index 2728d0271ec..17bfec664e3 100644 --- a/helm/litellm/templates/_helpers.tpl +++ b/helm/litellm/templates/_helpers.tpl @@ -560,3 +560,11 @@ shutdown drain window. {{- define "litellm.lensWorker.clickhouseName" -}} {{- printf "%s-lens-clickhouse" (include "litellm.fullname" . | trunc 47 | trimSuffix "-") -}} {{- end -}} + +{{- define "litellm.serverRootPath" -}} +{{- $root := .Values.serverRootPath | default "" | trimSuffix "/" -}} +{{- if and $root (or (not (regexMatch "^(/[A-Za-z0-9_.~-]+)+$" $root)) (regexMatch "(^|/)\\.\\.?(/|$)" $root)) -}} +{{- fail "serverRootPath must contain safe absolute path segments without traversal" -}} +{{- end -}} +{{- $root -}} +{{- end -}} diff --git a/helm/litellm/templates/backend/deployment.yaml b/helm/litellm/templates/backend/deployment.yaml index b752a7c10ff..3e6e60b6c84 100644 --- a/helm/litellm/templates/backend/deployment.yaml +++ b/helm/litellm/templates/backend/deployment.yaml @@ -57,6 +57,11 @@ spec: containerPort: 4001 protocol: TCP env: + {{- $root := include "litellm.serverRootPath" . }} + {{- if $root }} + - name: SERVER_ROOT_PATH + value: {{ $root | quote }} + {{- end }} {{- include "litellm.lensConnectionEnv" . | nindent 12 }} - name: LENS_WORKER_IMAGE value: {{ include "litellm.lensWorker.image" . | quote }} diff --git a/helm/litellm/templates/gateway/deployment.yaml b/helm/litellm/templates/gateway/deployment.yaml index 9b3b58c97ed..8d142b8a160 100644 --- a/helm/litellm/templates/gateway/deployment.yaml +++ b/helm/litellm/templates/gateway/deployment.yaml @@ -55,6 +55,11 @@ spec: containerPort: 4000 protocol: TCP env: + {{- $root := include "litellm.serverRootPath" . }} + {{- if $root }} + - name: SERVER_ROOT_PATH + value: {{ $root | quote }} + {{- end }} {{- include "litellm.lensConnectionEnv" . | nindent 12 }} {{- include "litellm.serverEnv" (dict "root" $ "component" .Values.gateway) | nindent 12 }} {{- if .Values.gateway.config.create }} diff --git a/helm/litellm/templates/ingress.yaml b/helm/litellm/templates/ingress.yaml index 7bfbe85db79..0cde7b880d1 100644 --- a/helm/litellm/templates/ingress.yaml +++ b/helm/litellm/templates/ingress.yaml @@ -1,4 +1,5 @@ {{- if .Values.ingress.enabled -}} +{{- $root := include "litellm.serverRootPath" . -}} {{- $gatewayName := include "litellm.gateway.fullname" . -}} {{- $backendName := include "litellm.backend.fullname" . -}} {{- $uiName := include "litellm.ui.fullname" . -}} @@ -6,6 +7,9 @@ {{- $backendPort := .Values.backend.service.port -}} {{- $uiPort := .Values.ui.service.port -}} {{- $controller := .Values.ingress.controller | default "alb" -}} +{{- if and $root (eq $controller "nginx") (contains "." $root) }} +{{- fail "serverRootPath containing dots is not supported with ingress.controller=nginx; use Gateway API or a prefix without dots" }} +{{- end }} {{- if not (has $controller (list "alb" "nginx")) }} {{- fail (printf "ingress.controller: unknown controller %q, expected one of alb, nginx" $controller) }} {{- end }} @@ -44,6 +48,9 @@ (dict "path" "/_next" "pathType" "Prefix") (dict "path" "/ui" "pathType" "Prefix") -}} +{{- if $root }} +{{- $uiPaths = append $uiPaths (dict "path" "/" "pathType" "Exact" "trailingSlash" true) }} +{{- end }} {{- if eq $controller "alb" }} {{- $uiPaths = append $uiPaths (dict "path" "/*.txt" "pathType" "ImplementationSpecific") }} {{- end }} @@ -118,7 +125,7 @@ spec: {{- range $uiPaths }} {{- $pathType := include "litellm.ingress.pathType" (dict "controller" $controller "path" .path "pathType" .pathType) }} {{- $builtinPathKeys = append $builtinPathKeys (printf "%s|%s" .path $pathType) }} - - path: {{ .path }} + - path: {{ if eq .path "/" }}{{ if .trailingSlash }}{{ printf "%s/" $root }}{{ else }}{{ $root | default "/" }}{{ end }}{{ else }}{{ printf "%s%s" $root .path }}{{ end }} pathType: {{ $pathType }} backend: service: @@ -131,14 +138,14 @@ spec: # /test/* MCP management endpoints fall to the backend catch-all. # Exact /debug/memory/summary reads a serving worker's RSS (the e2e memory # gate); the rest of /debug/* stays on the backend. - - path: /test + - path: {{ printf "%s/test" $root }} pathType: Exact backend: service: name: {{ $gatewayName }} port: number: {{ $gatewayPort }} - - path: /debug/memory/summary + - path: {{ printf "%s/debug/memory/summary" $root }} pathType: Exact backend: service: @@ -148,7 +155,7 @@ spec: {{- range $gatewayPrefixes }} {{- $pathType := include "litellm.ingress.pathType" (dict "controller" $controller "path" . "pathType" "Prefix") }} {{- $builtinPathKeys = append $builtinPathKeys (printf "%s|%s" . $pathType) }} - - path: {{ . }} + - path: {{ printf "%s%s" $root . }} pathType: {{ $pathType }} backend: service: @@ -158,7 +165,7 @@ spec: {{- end }} {{- if .Values.lensWorker.enabled }} {{- $builtinPathKeys = append $builtinPathKeys "/lens-ingest|Prefix" }} - - path: /lens-ingest + - path: {{ printf "%s/lens-ingest" $root }} pathType: Prefix backend: service: @@ -200,7 +207,7 @@ spec: {{- if has (printf "%s|%s" $extra.path $pathType) $builtinPathKeys }} {{- fail (printf "ingress.extraPaths[%d]: path %s with pathType %s is already routed by this chart, and a duplicate would take it over rather than add to it" $idx $extra.path $pathType) }} {{- end }} - - path: {{ $extra.path | quote }} + - path: {{ printf "%s%s" $root $extra.path | quote }} pathType: {{ $pathType }} backend: service: @@ -209,7 +216,7 @@ spec: number: {{ $target.port }} {{- end }} # --- Catch-all → backend (management API: /key/*, /user/*, /team/*, ...) --- - - path: / + - path: {{ $root | default "/" }} pathType: Prefix backend: service: diff --git a/helm/litellm/templates/ui/deployment.yaml b/helm/litellm/templates/ui/deployment.yaml index efee2d5fc34..14835ddc02c 100644 --- a/helm/litellm/templates/ui/deployment.yaml +++ b/helm/litellm/templates/ui/deployment.yaml @@ -52,6 +52,11 @@ spec: containerPort: 3000 protocol: TCP env: + {{- $root := include "litellm.serverRootPath" . }} + {{- if $root }} + - name: SERVER_ROOT_PATH + value: {{ $root | quote }} + {{- end }} {{- if .Values.ui.logLevel }} - name: LITELLM_LOG value: {{ .Values.ui.logLevel | quote }} diff --git a/helm/litellm/tests/server_root_path_tests.yaml b/helm/litellm/tests/server_root_path_tests.yaml new file mode 100644 index 00000000000..f1e0e215ee9 --- /dev/null +++ b/helm/litellm/tests/server_root_path_tests.yaml @@ -0,0 +1,73 @@ +suite: custom server root path +templates: + - gateway/deployment.yaml + - backend/deployment.yaml + - ui/deployment.yaml + - ingress.yaml +set: + database.writer.host: postgres + database.writer.dbname: litellm + lens.enabled: false + lensWorker.enabled: false +tests: + - it: configures all serving components with the same normalized prefix + set: + serverRootPath: /services/llm/ + templates: + - gateway/deployment.yaml + - backend/deployment.yaml + - ui/deployment.yaml + asserts: + - contains: + path: spec.template.spec.containers[0].env + content: + name: SERVER_ROOT_PATH + value: /services/llm + - it: routes only prefixed paths when ingress is enabled + template: ingress.yaml + set: + ingress.enabled: true + serverRootPath: /services/llm + ingress.extraPaths: + - path: /custom-provider + asserts: + - equal: + path: spec.rules[0].http.paths[0].path + value: /services/llm + - contains: + path: spec.rules[0].http.paths + content: + path: /services/llm/ui + pathType: Prefix + backend: + service: + name: RELEASE-NAME-litellm-ui + port: + number: 3000 + - contains: + path: spec.rules[0].http.paths + content: + path: /services/llm/ + pathType: Exact + backend: + service: + name: RELEASE-NAME-litellm-ui + port: + number: 3000 + - contains: + path: spec.rules[0].http.paths + content: + path: /services/llm/custom-provider + pathType: Prefix + backend: + service: + name: RELEASE-NAME-litellm-gateway + port: + number: 4000 + - it: rejects traversal + template: ui/deployment.yaml + set: + serverRootPath: /services/../llm + asserts: + - failedTemplate: + errorMessage: serverRootPath must contain safe absolute path segments without traversal diff --git a/helm/litellm/values.yaml b/helm/litellm/values.yaml index 5851c5a6cb1..38a6749b9fe 100644 --- a/helm/litellm/values.yaml +++ b/helm/litellm/values.yaml @@ -1,3 +1,5 @@ +serverRootPath: "" + # LiteLLM helm chart values nameOverride: "" @@ -194,7 +196,7 @@ billingMetrics: caSecretName: "" # existing Secret holding ca.crt exportIntervalMs: "" # push cadence; the proxy defaults to 60000 -# External Postgres connection. +# External Postgres connection. database: writer: host: "" diff --git a/tests/proxy_migration_tests/test_ui_root_path.py b/tests/proxy_migration_tests/test_ui_root_path.py new file mode 100644 index 00000000000..3825d4d89b9 --- /dev/null +++ b/tests/proxy_migration_tests/test_ui_root_path.py @@ -0,0 +1,86 @@ +import hashlib +import subprocess +import tempfile +import unittest +from pathlib import Path +from typing import Final + +REPO: Final = Path(__file__).resolve().parents[2] + + +class TestUIRootPath(unittest.TestCase): + def prepare(self, directory: Path, prefix: str) -> subprocess.CompletedProcess[str]: + return subprocess.run( + [ + "sh", + str(REPO / "ui" / "prepare-root-path.sh"), + str(directory / "source"), + str(directory / "runtime"), + str(REPO / "ui" / "nginx.conf"), + str(directory / "nginx.conf"), + prefix, + ], + text=True, + capture_output=True, + ) + + def source(self, directory: Path) -> Path: + source: Final = directory / "source" + source.mkdir() + (source / "index.html").write_text( + '' + '' + '' + ) + (source / "app.js").write_text('fetch("/litellm/.well-known/litellm-ui-config")') + (source / "font.woff2").write_bytes(bytes(range(256))) + return source + + def test_nested_prefix_preserves_original_export_and_binary_assets(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + directory: Final = Path(tmp) + source: Final = self.source(directory) + original: Final = (source / "index.html").read_bytes() + self.assertEqual(self.prepare(directory, "/services/llm/").returncode, 0) + runtime: Final = directory / "runtime" + self.assertIn("/services/llm/_next/app.js", (runtime / "index.html").read_text()) + self.assertIn( + 'name="litellm-server-root-path" content="/services/llm"', (runtime / "index.html").read_text() + ) + self.assertIn('href="/services/llm/get_favicon"', (runtime / "index.html").read_text()) + self.assertIn('src="/services/llm/ui/assets/logo.png"', (runtime / "index.html").read_text()) + self.assertEqual(runtime.stat().st_mode & 0o005, 0o005) + self.assertEqual((runtime / "index.html").stat().st_mode & 0o004, 0o004) + self.assertIn("/services/llm/.well-known/litellm-ui-config", (runtime / "app.js").read_text()) + self.assertEqual((source / "index.html").read_bytes(), original) + self.assertEqual((runtime / "font.woff2").read_bytes(), (source / "font.woff2").read_bytes()) + self.assertEqual(self.prepare(directory, "/services/llm/").returncode, 0) + self.assertNotIn("/services/llm/services/llm", (runtime / "app.js").read_text()) + self.assertEqual(self.prepare(directory, "/other/path").returncode, 0) + self.assertIn("/other/path/_next/app.js", (runtime / "index.html").read_text()) + self.assertNotIn("/services/llm", (runtime / "index.html").read_text()) + + def test_default_root_leaves_export_unchanged(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + directory: Final = Path(tmp) + source: Final = self.source(directory) + self.assertEqual(self.prepare(directory, "/").returncode, 0) + self.assertEqual((directory / "runtime" / "app.js").read_bytes(), (source / "app.js").read_bytes()) + + def test_rejects_unsafe_roots_before_writing(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + directory: Final = Path(tmp) + self.source(directory) + for prefix in ("relative", "/a/../b", "/a/./b", "/a//b", "/a|b", "/a?b", "/a\nb", "//", "/a//"): + with self.subTest(prefix=prefix): + self.assertNotEqual(self.prepare(directory, prefix).returncode, 0) + self.assertFalse((directory / "runtime").exists()) + + def test_source_can_be_read_only(self) -> None: + with tempfile.TemporaryDirectory() as tmp: + directory: Final = Path(tmp) + source: Final = self.source(directory) + (source / "app.js").chmod(0o444) + digest: Final = hashlib.sha256((source / "app.js").read_bytes()).hexdigest() + self.assertEqual(self.prepare(directory, "/services/llm").returncode, 0) + self.assertEqual(hashlib.sha256((source / "app.js").read_bytes()).hexdigest(), digest) diff --git a/ui/Dockerfile b/ui/Dockerfile index f14b631685a..02907be916b 100644 --- a/ui/Dockerfile +++ b/ui/Dockerfile @@ -35,6 +35,11 @@ COPY --from=builder /app/out /usr/share/nginx/html # Routing rules — see ui/nginx.conf for the full description. COPY ui/nginx.conf /etc/nginx/nginx.conf +COPY --chmod=755 ui/prepare-root-path.sh /usr/local/bin/prepare-ui-root-path +COPY --chmod=755 ui/docker-entrypoint.sh /usr/local/bin/litellm-ui-entrypoint + +ENTRYPOINT ["/usr/local/bin/litellm-ui-entrypoint"] + EXPOSE 3000/tcp # nginx as PID 1 in foreground; respects SIGTERM out of the box, so diff --git a/ui/docker-entrypoint.sh b/ui/docker-entrypoint.sh new file mode 100644 index 00000000000..ef843c137ca --- /dev/null +++ b/ui/docker-entrypoint.sh @@ -0,0 +1,12 @@ +#!/bin/sh +set -eu + +if [ "${1:-}" = nginx ] && [ -n "${SERVER_ROOT_PATH:-}" ] && [ "$SERVER_ROOT_PATH" != / ]; then + runtime_dir=$(mktemp -d /tmp/litellm-ui.XXXXXX) + /usr/local/bin/prepare-ui-root-path /usr/share/nginx/html "$runtime_dir" \ + /etc/nginx/nginx.conf "$runtime_dir/nginx.conf" "$SERVER_ROOT_PATH" + shift + set -- nginx -c "$runtime_dir/nginx.conf" "$@" +fi + +exec /docker-entrypoint.sh "$@" diff --git a/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx b/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx index 6a61f5ed85f..91a94f54103 100644 --- a/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx +++ b/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx @@ -1,6 +1,7 @@ import { describe, it, expect, vi, beforeEach } from "vitest"; import { render, screen, waitFor } from "@testing-library/react"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { setServerRootPath } from "@/lib/serverRootPath"; import LoginPage from "./LoginPage"; const mockPush = vi.fn(); @@ -69,6 +70,7 @@ const createQueryClient = () => describe("LoginPage", () => { beforeEach(() => { + setServerRootPath("/"); vi.clearAllMocks(); mockPush.mockClear(); mockReplace.mockClear(); @@ -98,12 +100,16 @@ describe("LoginPage", () => { }); }); - it("should call router.replace to dashboard when jwt is valid", async () => { + it.each([ + ["/", "/ui"], + ["/services/llm/", "/services/llm/ui"], + ])("keeps valid-token navigation under %s", async (root, expectedPath) => { + setServerRootPath(root); const validToken = "valid-token"; (useUIConfig as ReturnType).mockReturnValue({ data: { auto_redirect_to_sso: false, - server_root_path: "/", + server_root_path: root, proxy_base_url: null, sso_configured: false, }, @@ -120,7 +126,7 @@ describe("LoginPage", () => { ); await waitFor(() => { - expect(mockReplace).toHaveBeenCalledWith("/ui"); + expect(mockReplace).toHaveBeenCalledWith(expectedPath); }); }); diff --git a/ui/litellm-dashboard/src/app/login/LoginPage.tsx b/ui/litellm-dashboard/src/app/login/LoginPage.tsx index 14d50555dec..fdac8d213b9 100644 --- a/ui/litellm-dashboard/src/app/login/LoginPage.tsx +++ b/ui/litellm-dashboard/src/app/login/LoginPage.tsx @@ -18,6 +18,7 @@ import { useZodForm } from "@/lib/forms/useZodForm"; import { clearTokenCookies, getCookieFromDocument } from "@/utils/cookieUtils"; import { isJwtExpired } from "@/utils/jwtUtils"; import { consumeReturnUrl, getLoginUrl, getReturnUrl, isValidReturnUrl } from "@/utils/returnUrlUtils"; +import { uiHref } from "@/utils/uiHref"; import { CircleAlert, Info, TriangleAlert, X } from "lucide-react"; import { useRouter } from "next/navigation"; import { useEffect, useId, useState } from "react"; @@ -102,7 +103,7 @@ function LoginPageContent() { params.delete("code"); const cleanSearch = params.toString(); window.history.replaceState(null, "", window.location.pathname + (cleanSearch ? `?${cleanSearch}` : "")); - router.replace("/ui/?login=success"); + router.replace(`${uiHref("")}?login=success`); }); return; } @@ -122,7 +123,7 @@ function LoginPageContent() { if (returnUrl) { router.replace(returnUrl); } else { - router.replace("/ui"); + router.replace(uiHref("").replace(/\/$/, "")); } return; } @@ -156,7 +157,7 @@ function LoginPageContent() { if (selectedWorker) { selectWorker(selectedWorker.worker_id); // Stay on the CP's UI — proxyBaseUrl already points at the worker - router.push("/ui/?login=success"); + router.push(`${uiHref("")}?login=success`); } else { // Normal (non-control-plane) login — follow the server's redirect const returnUrl = consumeReturnUrl(); diff --git a/ui/litellm-dashboard/src/lib/serverRootPath.test.tsx b/ui/litellm-dashboard/src/lib/serverRootPath.test.tsx new file mode 100644 index 00000000000..2613f8b2876 --- /dev/null +++ b/ui/litellm-dashboard/src/lib/serverRootPath.test.tsx @@ -0,0 +1,22 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; + +afterEach(() => { + document.head.innerHTML = ""; + vi.resetModules(); +}); + +describe("initial server root path", () => { + it("uses the root when runtime metadata is absent", async () => { + const { serverRootPath } = await import("./serverRootPath"); + expect(serverRootPath).toBe("/"); + }); + + it("uses image runtime metadata before backend configuration arrives", async () => { + document.head.innerHTML = ''; + const { serverRootPath, setServerRootPath } = await import("./serverRootPath"); + expect(serverRootPath).toBe("/services/llm"); + setServerRootPath("/configured"); + const updated = await import("./serverRootPath"); + expect(updated.serverRootPath).toBe("/configured"); + }); +}); diff --git a/ui/litellm-dashboard/src/lib/serverRootPath.ts b/ui/litellm-dashboard/src/lib/serverRootPath.ts index 76eb9d629db..b1d2d6e67a2 100644 --- a/ui/litellm-dashboard/src/lib/serverRootPath.ts +++ b/ui/litellm-dashboard/src/lib/serverRootPath.ts @@ -5,7 +5,10 @@ * networking module. `networking` re-exports `serverRootPath` and updates it via * `setServerRootPath` from its UI-config bootstrap. */ -export let serverRootPath = "/"; +export let serverRootPath = + typeof document === "undefined" + ? "/" + : document.querySelector('meta[name="litellm-server-root-path"]')?.content || "/"; export const setServerRootPath = (rootPath: string): void => { serverRootPath = rootPath; diff --git a/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts b/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts index 3d1e83ad236..a94f1e5577b 100644 --- a/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts +++ b/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts @@ -1,5 +1,7 @@ // @vitest-environment jsdom +import { setServerRootPath } from "@/lib/serverRootPath"; + import { buildLoginUrlWithReturn, clearStoredReturnUrl, @@ -36,6 +38,7 @@ describe("returnUrlUtils", () => { }); afterEach(() => { + setServerRootPath("/"); // Restore original location Object.defineProperty(window, "location", { value: originalLocation, @@ -102,6 +105,17 @@ describe("returnUrlUtils", () => { }); describe("getLoginUrl", () => { + it("keeps a nested root in same-origin SSO return URLs", () => { + setServerRootPath("/services/llm/"); + expect(getLoginUrl()).toBe("/services/llm/ui/login/"); + expect(getLoginUrl("https://platform.example.com")).toBe( + "https://platform.example.com/services/llm/ui/login/", + ); + expect(getLoginUrl("https://platform.example.com/services/llm/")).toBe( + "https://platform.example.com/services/llm/ui/login/", + ); + }); + it("should build a relative login URL with a trailing slash", () => { expect(getLoginUrl()).toBe("/ui/login/"); }); diff --git a/ui/litellm-dashboard/src/utils/returnUrlUtils.ts b/ui/litellm-dashboard/src/utils/returnUrlUtils.ts index b3cc5345bb1..50b0a32bd87 100644 --- a/ui/litellm-dashboard/src/utils/returnUrlUtils.ts +++ b/ui/litellm-dashboard/src/utils/returnUrlUtils.ts @@ -1,3 +1,6 @@ +import { serverRootPath } from "@/lib/serverRootPath"; +import { resolveApiBase } from "@/lib/http/resolveApiBase"; + /** * Utility functions for managing return URLs during authentication flows. * @@ -14,7 +17,7 @@ const RETURN_URL_COOKIE_NAME = "litellm_return_url"; const RETURN_URL_PARAM = "redirect_to"; export function getLoginUrl(baseUrl: string = ""): string { - return `${baseUrl}/ui/login/`; + return `${resolveApiBase({ explicitBase: baseUrl, serverRootPath })}/ui/login/`; } /** diff --git a/ui/prepare-root-path.sh b/ui/prepare-root-path.sh new file mode 100644 index 00000000000..926d5a0b775 --- /dev/null +++ b/ui/prepare-root-path.sh @@ -0,0 +1,58 @@ +#!/bin/sh +set -eu + +source_dir=$1 +runtime_dir=$2 +source_config=$3 +runtime_config=$4 +prefix=${5%/} + +case "$prefix" in + ""|/*) ;; + *) echo "SERVER_ROOT_PATH must start with /" >&2; exit 1 ;; +esac +case "$prefix" in + *[!a-zA-Z0-9_./~-]*|*//*|*/./*|*/../*|*/.|*/..|*/) + echo "SERVER_ROOT_PATH must contain safe path segments without traversal" >&2 + exit 1 + ;; +esac + +mkdir -p "$runtime_dir" +cp -R "$source_dir/." "$runtime_dir/" +chmod -R u+rwX,go+rX "$runtime_dir" + +if [ -n "$prefix" ]; then + find "$runtime_dir" -type f \( -name '*.html' -o -name '*.js' -o -name '*.css' -o -name '*.txt' -o -name '*.json' \) \ + -exec sh -eu -c ' + prefix=$1 + shift + for file do + sed -e "s|/litellm-asset-prefix|$prefix|g" \ + -e "s|/litellm/\.well-known/litellm-ui-config|$prefix/.well-known/litellm-ui-config|g" \ + "$file" > "$file.tmp" + case "$file" in + *.html) + sed -e "s|||g" \ + -e "s|src=\"/ui/assets/|src=\"$prefix/ui/assets/|g" \ + -e "s|href=\"/get_favicon\"|href=\"$prefix/get_favicon\"|g" \ + "$file.tmp" > "$file" + rm "$file.tmp" + ;; + *) mv "$file.tmp" "$file" ;; + esac + done + ' sh "$prefix" {} + +fi + +escaped_runtime=$(printf '%s' "$runtime_dir" | sed 's/[\\&|]/\\&/g') +escaped_prefix=$(printf '%s' "$prefix" | sed 's/\./\\\\./g') +sed "s|/usr/share/nginx/html|$escaped_runtime|g" "$source_config" > "$runtime_config" +if [ -n "$prefix" ]; then + sed "/server_name _;/a\\ + absolute_redirect off;\\ + rewrite ^$escaped_prefix\$ $prefix/ui/ redirect;\\ + rewrite ^$escaped_prefix(/.*)\$ \$1 last;\\ +" "$runtime_config" > "$runtime_config.tmp" + mv "$runtime_config.tmp" "$runtime_config" +fi From eb9e706206c23360b5788bb88823ce6629fc3be2 Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 8 Oct 2026 10:29:21 +0200 Subject: [PATCH 02/13] style(ui): format prefix-aware login URL regression test --- ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts b/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts index a94f1e5577b..142cafc2fc1 100644 --- a/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts +++ b/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts @@ -108,9 +108,7 @@ describe("returnUrlUtils", () => { it("keeps a nested root in same-origin SSO return URLs", () => { setServerRootPath("/services/llm/"); expect(getLoginUrl()).toBe("/services/llm/ui/login/"); - expect(getLoginUrl("https://platform.example.com")).toBe( - "https://platform.example.com/services/llm/ui/login/", - ); + expect(getLoginUrl("https://platform.example.com")).toBe("https://platform.example.com/services/llm/ui/login/"); expect(getLoginUrl("https://platform.example.com/services/llm/")).toBe( "https://platform.example.com/services/llm/ui/login/", ); From 2269377e502da73f04531f2dc26ba219a1ec06f5 Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 8 Oct 2026 10:34:24 +0200 Subject: [PATCH 03/13] test(helm): include config template in custom-prefix suite --- helm/litellm/tests/server_root_path_tests.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/helm/litellm/tests/server_root_path_tests.yaml b/helm/litellm/tests/server_root_path_tests.yaml index f1e0e215ee9..575554087f8 100644 --- a/helm/litellm/tests/server_root_path_tests.yaml +++ b/helm/litellm/tests/server_root_path_tests.yaml @@ -1,5 +1,6 @@ suite: custom server root path templates: + - gateway/configmap.yaml - gateway/deployment.yaml - backend/deployment.yaml - ui/deployment.yaml From c137ad01cefde3241498be72fafe1d0c7314421f Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 8 Oct 2026 11:41:46 +0200 Subject: [PATCH 04/13] fix(ui): prefix static favicon URLs in custom-root exports --- tests/proxy_migration_tests/test_ui_root_path.py | 3 ++- ui/prepare-root-path.sh | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/proxy_migration_tests/test_ui_root_path.py b/tests/proxy_migration_tests/test_ui_root_path.py index 3825d4d89b9..7978ca394b9 100644 --- a/tests/proxy_migration_tests/test_ui_root_path.py +++ b/tests/proxy_migration_tests/test_ui_root_path.py @@ -28,7 +28,7 @@ class TestUIRootPath(unittest.TestCase): source: Final = directory / "source" source.mkdir() (source / "index.html").write_text( - '' + '' '' '' ) @@ -48,6 +48,7 @@ class TestUIRootPath(unittest.TestCase): 'name="litellm-server-root-path" content="/services/llm"', (runtime / "index.html").read_text() ) self.assertIn('href="/services/llm/get_favicon"', (runtime / "index.html").read_text()) + self.assertIn('href="/services/llm/favicon.ico?version=1"', (runtime / "index.html").read_text()) self.assertIn('src="/services/llm/ui/assets/logo.png"', (runtime / "index.html").read_text()) self.assertEqual(runtime.stat().st_mode & 0o005, 0o005) self.assertEqual((runtime / "index.html").stat().st_mode & 0o004, 0o004) diff --git a/ui/prepare-root-path.sh b/ui/prepare-root-path.sh index 926d5a0b775..b55341707de 100644 --- a/ui/prepare-root-path.sh +++ b/ui/prepare-root-path.sh @@ -36,6 +36,7 @@ if [ -n "$prefix" ]; then sed -e "s|||g" \ -e "s|src=\"/ui/assets/|src=\"$prefix/ui/assets/|g" \ -e "s|href=\"/get_favicon\"|href=\"$prefix/get_favicon\"|g" \ + -e "s|href=\"/favicon.ico|href=\"$prefix/favicon.ico|g" \ "$file.tmp" > "$file" rm "$file.tmp" ;; From 6f82d81bd5c44e8f55db6de0f0ae6a439fe5eefe Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 8 Oct 2026 11:44:17 +0200 Subject: [PATCH 05/13] fix(ui): preserve favicon prefix in exported router payloads --- tests/proxy_migration_tests/test_ui_root_path.py | 2 ++ ui/prepare-root-path.sh | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/proxy_migration_tests/test_ui_root_path.py b/tests/proxy_migration_tests/test_ui_root_path.py index 7978ca394b9..474696772af 100644 --- a/tests/proxy_migration_tests/test_ui_root_path.py +++ b/tests/proxy_migration_tests/test_ui_root_path.py @@ -32,6 +32,7 @@ class TestUIRootPath(unittest.TestCase): '' '' ) + (source / "index.txt").write_text('[{"href":"/favicon.ico?version=1"}]') (source / "app.js").write_text('fetch("/litellm/.well-known/litellm-ui-config")') (source / "font.woff2").write_bytes(bytes(range(256))) return source @@ -50,6 +51,7 @@ class TestUIRootPath(unittest.TestCase): self.assertIn('href="/services/llm/get_favicon"', (runtime / "index.html").read_text()) self.assertIn('href="/services/llm/favicon.ico?version=1"', (runtime / "index.html").read_text()) self.assertIn('src="/services/llm/ui/assets/logo.png"', (runtime / "index.html").read_text()) + self.assertIn("/services/llm/favicon.ico?version=1", (runtime / "index.txt").read_text()) self.assertEqual(runtime.stat().st_mode & 0o005, 0o005) self.assertEqual((runtime / "index.html").stat().st_mode & 0o004, 0o004) self.assertIn("/services/llm/.well-known/litellm-ui-config", (runtime / "app.js").read_text()) diff --git a/ui/prepare-root-path.sh b/ui/prepare-root-path.sh index b55341707de..bdd17e25840 100644 --- a/ui/prepare-root-path.sh +++ b/ui/prepare-root-path.sh @@ -30,13 +30,13 @@ if [ -n "$prefix" ]; then for file do sed -e "s|/litellm-asset-prefix|$prefix|g" \ -e "s|/litellm/\.well-known/litellm-ui-config|$prefix/.well-known/litellm-ui-config|g" \ + -e "s|/favicon.ico|$prefix/favicon.ico|g" \ "$file" > "$file.tmp" case "$file" in *.html) sed -e "s|||g" \ -e "s|src=\"/ui/assets/|src=\"$prefix/ui/assets/|g" \ -e "s|href=\"/get_favicon\"|href=\"$prefix/get_favicon\"|g" \ - -e "s|href=\"/favicon.ico|href=\"$prefix/favicon.ico|g" \ "$file.tmp" > "$file" rm "$file.tmp" ;; From 43b5fe2e55df8af5ab4d9335eb2f6bccdc37273c Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 8 Oct 2026 13:37:19 +0200 Subject: [PATCH 06/13] test(ui): run runtime prefix regressions in UI CI --- .github/workflows/test-litellm-ui-unit.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/test-litellm-ui-unit.yml b/.github/workflows/test-litellm-ui-unit.yml index fcd61cedd50..e02d2b5c4cd 100644 --- a/.github/workflows/test-litellm-ui-unit.yml +++ b/.github/workflows/test-litellm-ui-unit.yml @@ -37,6 +37,11 @@ jobs: with: category: ui + - name: Run UI runtime prefix regression tests + if: steps.changes.outputs.decision != 'skip' + working-directory: . + run: python3 -m unittest discover -s tests/proxy_migration_tests -p test_ui_root_path.py + - name: Setup Node.js if: steps.changes.outputs.decision != 'skip' uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0 From 327c0da347e45119d2e411f15de9bce91281dfaa Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 8 Oct 2026 13:56:51 +0200 Subject: [PATCH 07/13] fix(proxy): preserve worker login bases and Lens prefix routing --- helm/litellm/README.md | 2 + helm/litellm/templates/_helpers.tpl | 2 +- helm/litellm/templates/lens/deployment.yaml | 5 ++ .../tests/lens_endpoint_defaults_tests.yaml | 10 ++++ helm/litellm/tests/lens_service_tests.yaml | 14 ++++++ litellm-rust/crates/lens/src/config.rs | 47 +++++++++++++++++++ litellm-rust/crates/lens/src/lib.rs | 6 ++- litellm-rust/crates/lens/src/main.rs | 15 +++--- litellm-rust/crates/lens/tests/receiver.rs | 34 +++++++++++--- .../src/app/login/LoginPage.test.tsx | 15 ++++-- .../src/app/login/LoginPage.tsx | 2 +- .../src/utils/returnUrlUtils.test.ts | 11 ++++- .../src/utils/returnUrlUtils.ts | 3 +- 13 files changed, 144 insertions(+), 22 deletions(-) diff --git a/helm/litellm/README.md b/helm/litellm/README.md index b3c3080d076..9a40ab6f9e3 100644 --- a/helm/litellm/README.md +++ b/helm/litellm/README.md @@ -23,6 +23,8 @@ The chart passes `SERVER_ROOT_PATH` to gateway, backend and UI. The UI image pre When the chart's ingress is enabled, its built-in routes and `ingress.extraPaths` are prefixed. Paths in `extraPaths` remain root-relative, for example `/custom-provider`, and the chart adds the configured prefix. The ingress must preserve the path sent upstream. Prefixes containing dots require Gateway API or the ALB controller; ingress-nginx cannot preserve all of the chart's exact matches with its dotted-path normalization +If Lens is enabled, its shared-ingress upload address also includes the prefix. A Lens worker image built with this implementation accepts that prefixed ingestion route while keeping container health probes and internal routes unchanged. An explicit `lensWorker.publicUrl` or dedicated Lens ingress keeps its own address + With an external Gateway API controller, route UI requests to port 3000, inference requests to port 4000, and management/configuration/SSO to port 4001. Preserve the prefix for Python services. The UI accepts both a preserved prefix and a prefix stripped by `URLRewrite` This Istio example covers the UI, configuration/SSO, chat completions and model listing. Add other inference routes from `templates/ingress.yaml` as needed. Do not send all `/v1` paths to the gateway: several management endpoints also use that version prefix diff --git a/helm/litellm/templates/_helpers.tpl b/helm/litellm/templates/_helpers.tpl index 17bfec664e3..7e6d8aa39c3 100644 --- a/helm/litellm/templates/_helpers.tpl +++ b/helm/litellm/templates/_helpers.tpl @@ -551,7 +551,7 @@ shutdown drain window. {{- printf "%s://%s" (ternary "https" "http" $tls) (required "lensWorker.ingress.host is required" .Values.lensWorker.ingress.host) -}} {{- else if and .Values.ingress.enabled .Values.ingress.host -}} {{- $tls := or (not (empty .Values.ingress.tls)) (hasKey .Values.ingress.annotations "alb.ingress.kubernetes.io/certificate-arn") -}} -{{- printf "%s://%s/lens-ingest" (ternary "https" "http" $tls) .Values.ingress.host -}} +{{- printf "%s://%s%s/lens-ingest" (ternary "https" "http" $tls) .Values.ingress.host (include "litellm.serverRootPath" .) -}} {{- else -}} {{- fail "lensWorker.publicUrl is required when there is no single ingress hostname" -}} {{- end -}} diff --git a/helm/litellm/templates/lens/deployment.yaml b/helm/litellm/templates/lens/deployment.yaml index 2ba13609188..951e1bf8081 100644 --- a/helm/litellm/templates/lens/deployment.yaml +++ b/helm/litellm/templates/lens/deployment.yaml @@ -40,6 +40,11 @@ spec: capabilities: drop: [ALL] env: + {{- $root := include "litellm.serverRootPath" . }} + {{- if $root }} + - name: SERVER_ROOT_PATH + value: {{ $root | quote }} + {{- end }} - name: LITELLM_URL value: {{ .Values.lensWorker.url | default (printf "http://%s:%v" (include "litellm.backend.fullname" .) .Values.backend.service.port) | quote }} - name: LITELLM_LENS_SERVICE_TOKEN diff --git a/helm/litellm/tests/lens_endpoint_defaults_tests.yaml b/helm/litellm/tests/lens_endpoint_defaults_tests.yaml index 2d98dcf471e..d1930a675c9 100644 --- a/helm/litellm/tests/lens_endpoint_defaults_tests.yaml +++ b/helm/litellm/tests/lens_endpoint_defaults_tests.yaml @@ -10,6 +10,16 @@ set: - hosts: [gateway.example] secretName: tls tests: + - it: derives the prefixed shared ingestion address + set: + serverRootPath: /services/llm/ + template: gateway/deployment.yaml + asserts: + - contains: + path: spec.template.spec.containers[0].env + content: + name: LITELLM_LENS_PUBLIC_URL + value: https://gateway.example/services/llm/lens-ingest - it: derives the trace endpoint from the deployment hostname and TLS template: gateway/deployment.yaml asserts: diff --git a/helm/litellm/tests/lens_service_tests.yaml b/helm/litellm/tests/lens_service_tests.yaml index 81ad93bbeee..8b319ee5d80 100644 --- a/helm/litellm/tests/lens_service_tests.yaml +++ b/helm/litellm/tests/lens_service_tests.yaml @@ -8,6 +8,20 @@ templates: - lens/service.yaml - lens/deployment.yaml tests: +- it: passes the normalized prefix to the Lens ingestion listener + template: lens/deployment.yaml + set: + serverRootPath: /services/llm/ + lensWorker.enabled: true + lensWorker.publicUrl: https://gateway.example/services/llm/lens-ingest + lensWorker.serviceTokenSecret.name: lens-service + lensWorker.clickhouseSecret.name: lens-storage + asserts: + - contains: + path: spec.template.spec.containers[0].env + content: + name: SERVER_ROOT_PATH + value: /services/llm - it: connects gateway/deployment.yaml to the shared Lens service template: gateway/deployment.yaml set: &id001 diff --git a/litellm-rust/crates/lens/src/config.rs b/litellm-rust/crates/lens/src/config.rs index 347800efeea..3abc21e10f1 100644 --- a/litellm-rust/crates/lens/src/config.rs +++ b/litellm-rust/crates/lens/src/config.rs @@ -7,6 +7,7 @@ use std::{net::SocketAddr, sync::Arc, time::Duration}; pub struct Config { pub address: SocketAddr, + pub server_root_path: String, pub proxy_url: url::Url, pub worker_token: String, pub service_token: String, @@ -44,6 +45,9 @@ impl Config { )); } Ok(Self { + server_root_path: normalize_server_root_path( + &std::env::var("SERVER_ROOT_PATH").unwrap_or_default(), + )?, address: std::env::var("LITELLM_LENS_LISTEN") .unwrap_or_else(|_| "0.0.0.0:4318".into()) .parse() @@ -65,6 +69,49 @@ impl Config { } } +fn normalize_server_root_path(value: &str) -> Result { + let root = value.strip_suffix('/').unwrap_or(value); + if root.is_empty() { + return Ok(String::new()); + } + if !root.starts_with('/') + || root.split('/').skip(1).any(|segment| { + segment.is_empty() + || matches!(segment, "." | "..") + || !segment + .bytes() + .all(|byte| byte.is_ascii_alphanumeric() || b"_.~-".contains(&byte)) + }) + { + return Err(Error::Configuration("SERVER_ROOT_PATH")); + } + Ok(root.to_owned()) +} + +#[cfg(test)] +mod tests { + use super::normalize_server_root_path; + use rstest::rstest; + + #[rstest] + #[case::empty("", "")] + #[case::root("/", "")] + #[case::nested("/services/llm", "/services/llm")] + #[case::trailing_slash("/services/llm/", "/services/llm")] + fn normalizes_server_root_path(#[case] input: &str, #[case] expected: &str) { + assert_eq!(normalize_server_root_path(input).unwrap(), expected); + } + + #[rstest] + #[case::relative("relative")] + #[case::traversal("/a/../b")] + #[case::double_slash("/a//b")] + #[case::query("/a?b")] + fn rejects_unsafe_server_root_path(#[case] input: &str) { + assert!(normalize_server_root_path(input).is_err()); + } +} + fn clickhouse_url() -> Result { if let Ok(url) = required("CLICKHOUSE_URL") { return Ok(url); diff --git a/litellm-rust/crates/lens/src/lib.rs b/litellm-rust/crates/lens/src/lib.rs index a3038a0f975..8f2a896d232 100644 --- a/litellm-rust/crates/lens/src/lib.rs +++ b/litellm-rust/crates/lens/src/lib.rs @@ -93,6 +93,10 @@ async fn wait_for_read_slot

( } pub fn router(state: Arc) -> Router { + router_with_root_path(state, "") +} + +pub fn router_with_root_path(state: Arc, server_root_path: &str) -> Router { let public = Router::new() .route("/health/live", get(|| async { StatusCode::OK })) .route("/health/ready", get(ready)) @@ -111,7 +115,7 @@ pub fn router(state: Arc) -> Router { ); public .clone() - .nest("/lens-ingest", public) + .nest(&format!("{server_root_path}/lens-ingest"), public) .merge( Router::new() .route("/internal/read", post(read)) diff --git a/litellm-rust/crates/lens/src/main.rs b/litellm-rust/crates/lens/src/main.rs index 135ed69cf38..42b691b1468 100644 --- a/litellm-rust/crates/lens/src/main.rs +++ b/litellm-rust/crates/lens/src/main.rs @@ -2,7 +2,7 @@ use litellm_lens::{ State, Storage, auth, config::{Config, http_client}, control::Control, - provision, router, + provision, router_with_root_path, worker::Worker, }; use std::{io::Write, sync::Arc, time::Duration}; @@ -63,11 +63,14 @@ async fn run() -> Result<(), litellm_lens::Error> { let mut worker = tokio::spawn(Worker::new(control, config.release).serve()); let (shutdown, stopping) = tokio::sync::oneshot::channel::<()>(); let mut server = tokio::spawn(async move { - axum::serve(listener, router(state)) - .with_graceful_shutdown(async { - let _ = stopping.await; - }) - .await + axum::serve( + listener, + router_with_root_path(state, &config.server_root_path), + ) + .with_graceful_shutdown(async { + let _ = stopping.await; + }) + .await }); let outcome = tokio::select! { _ = shutdown_signal() => Ok(()), diff --git a/litellm-rust/crates/lens/tests/receiver.rs b/litellm-rust/crates/lens/tests/receiver.rs index 2af3c67955a..69ef14d7e18 100644 --- a/litellm-rust/crates/lens/tests/receiver.rs +++ b/litellm-rust/crates/lens/tests/receiver.rs @@ -2,7 +2,7 @@ use litellm_lens::{ State, Storage, auth::{Credential, Snapshot, unix_seconds}, config::http_client, - router, + router_with_root_path, }; use litellm_traces::Tenant; use litellm_traces_clickhouse::Config; @@ -37,6 +37,10 @@ impl Drop for Server { } async fn serve(clickhouse: &str, ready: bool) -> Server { + serve_with_root_path(clickhouse, ready, "").await +} + +async fn serve_with_root_path(clickhouse: &str, ready: bool, server_root_path: &str) -> Server { let storage = Storage::new( Config::new("litellm".into(), clickhouse, 14, 65_536).unwrap(), http_client().unwrap(), @@ -62,7 +66,7 @@ async fn serve(clickhouse: &str, ready: bool) -> Server { .unwrap(); let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); let url = format!("http://{}", listener.local_addr().unwrap()); - let app = router(state.clone()); + let app = router_with_root_path(state.clone(), server_root_path); let task = tokio::spawn(async { axum::serve(listener, app).await.unwrap(); }); @@ -323,26 +327,42 @@ async fn ingestion_confirms_storage_and_overwrites_exporter_tenant() { } #[rstest] +#[case::root("")] +#[case::nested("/services/llm")] #[tokio::test] -async fn shared_ingress_prefix_exposes_uploads_without_internal_control_routes() { +async fn shared_ingress_prefix_exposes_uploads_without_internal_control_routes( + #[case] server_root_path: &str, +) { let store = MockServer::start().await; Mock::given(method("POST")) .respond_with(ResponseTemplate::new(200)) .expect(1) .mount(&store) .await; - let server = serve(&store.uri(), true).await; + let server = serve_with_root_path(&store.uri(), true, server_root_path).await; let client = http_client().unwrap(); let upload = client - .post(format!("{}/lens-ingest/v1/traces", server.url)) + .post(format!( + "{}{server_root_path}/lens-ingest/v1/traces", + server.url + )) .bearer_auth(KEY) .json(&export()) .send() .await .unwrap(); assert_eq!(upload.status(), 200); + let health = client + .get(format!("{}/health/live", server.url)) + .send() + .await + .unwrap(); + assert_eq!(health.status(), 200); let internal = client - .get(format!("{}/lens-ingest/internal/status", server.url)) + .get(format!( + "{}{server_root_path}/lens-ingest/internal/status", + server.url + )) .bearer_auth(SERVICE_TOKEN) .send() .await @@ -351,7 +371,7 @@ async fn shared_ingress_prefix_exposes_uploads_without_internal_control_routes() let preflight = client .request( http::Method::OPTIONS, - format!("{}/lens-ingest/v1/traces", server.url), + format!("{}{server_root_path}/lens-ingest/v1/traces", server.url), ) .header("origin", "https://dashboard.example") .header("access-control-request-method", "POST") diff --git a/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx b/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx index 91a94f54103..2a81dda7199 100644 --- a/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx +++ b/ui/litellm-dashboard/src/app/login/LoginPage.test.tsx @@ -1,5 +1,5 @@ import { describe, it, expect, vi, beforeEach } from "vitest"; -import { render, screen, waitFor } from "@testing-library/react"; +import { fireEvent, render, screen, waitFor } from "@testing-library/react"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import { setServerRootPath } from "@/lib/serverRootPath"; import LoginPage from "./LoginPage"; @@ -241,11 +241,15 @@ describe("LoginPage", () => { expect(mockReplace).not.toHaveBeenCalled(); }); - it("should show Login with SSO button when sso_configured is true", async () => { + it.each([ + ["/", "/ui/login/"], + ["/services/llm", "/services/llm/ui/login/"], + ])("returns SSO to the control plane UI under %s", async (root, expectedPath) => { + setServerRootPath(root); (useUIConfig as ReturnType).mockReturnValue({ data: { auto_redirect_to_sso: false, - server_root_path: "/", + server_root_path: root, proxy_base_url: null, sso_configured: true, }, @@ -265,7 +269,10 @@ describe("LoginPage", () => { expect(screen.getByRole("heading", { name: "Login" })).toBeInTheDocument(); }); - expect(screen.getByRole("button", { name: "Login with SSO" })).toBeInTheDocument(); + fireEvent.click(screen.getByRole("button", { name: "Login with SSO" })); + expect(mockPush).toHaveBeenCalledWith( + `http://localhost:4000/sso/key/generate?return_to=${encodeURIComponent(new URL(expectedPath, window.location.origin).href)}`, + ); }); it("should show disabled Login with SSO button with popover when sso_configured is false", async () => { diff --git a/ui/litellm-dashboard/src/app/login/LoginPage.tsx b/ui/litellm-dashboard/src/app/login/LoginPage.tsx index fdac8d213b9..b827c36d3a0 100644 --- a/ui/litellm-dashboard/src/app/login/LoginPage.tsx +++ b/ui/litellm-dashboard/src/app/login/LoginPage.tsx @@ -339,7 +339,7 @@ function LoginPageContent() { // SSO on the worker (or this instance if no worker), always // include return_to so the callback redirects back here const ssoBase = selectedWorker?.url ?? getProxyBaseUrl(); - const returnTo = encodeURIComponent(getLoginUrl(window.location.origin)); + const returnTo = encodeURIComponent(new URL(getLoginUrl(), window.location.origin).href); router.push(`${ssoBase}/sso/key/generate?return_to=${returnTo}`); }} className="w-full" diff --git a/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts b/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts index 142cafc2fc1..6c70288e061 100644 --- a/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts +++ b/ui/litellm-dashboard/src/utils/returnUrlUtils.test.ts @@ -108,12 +108,21 @@ describe("returnUrlUtils", () => { it("keeps a nested root in same-origin SSO return URLs", () => { setServerRootPath("/services/llm/"); expect(getLoginUrl()).toBe("/services/llm/ui/login/"); - expect(getLoginUrl("https://platform.example.com")).toBe("https://platform.example.com/services/llm/ui/login/"); + expect(new URL(getLoginUrl(), "https://platform.example.com").href).toBe( + "https://platform.example.com/services/llm/ui/login/", + ); expect(getLoginUrl("https://platform.example.com/services/llm/")).toBe( "https://platform.example.com/services/llm/ui/login/", ); }); + it("keeps worker mount paths independent of the control plane prefix", () => { + setServerRootPath("/services/llm"); + expect(getLoginUrl("https://worker.example.com")).toBe("https://worker.example.com/ui/login/"); + expect(getLoginUrl("https://worker.example.com/worker/")).toBe("https://worker.example.com/worker/ui/login/"); + expect(getLoginUrl("/")).toBe("/ui/login/"); + }); + it("should build a relative login URL with a trailing slash", () => { expect(getLoginUrl()).toBe("/ui/login/"); }); diff --git a/ui/litellm-dashboard/src/utils/returnUrlUtils.ts b/ui/litellm-dashboard/src/utils/returnUrlUtils.ts index 50b0a32bd87..6b208154ba2 100644 --- a/ui/litellm-dashboard/src/utils/returnUrlUtils.ts +++ b/ui/litellm-dashboard/src/utils/returnUrlUtils.ts @@ -17,7 +17,8 @@ const RETURN_URL_COOKIE_NAME = "litellm_return_url"; const RETURN_URL_PARAM = "redirect_to"; export function getLoginUrl(baseUrl: string = ""): string { - return `${resolveApiBase({ explicitBase: baseUrl, serverRootPath })}/ui/login/`; + const base = baseUrl.trim(); + return `${base ? base.replace(/\/+$/, "") : resolveApiBase({ serverRootPath })}/ui/login/`; } /** From 11486173c838421982a39f7c45640379a097a573 Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 8 Oct 2026 13:57:38 +0200 Subject: [PATCH 08/13] test(lens): place configuration tests after production items --- litellm-rust/crates/lens/src/config.rs | 48 +++++++++++++------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/litellm-rust/crates/lens/src/config.rs b/litellm-rust/crates/lens/src/config.rs index 3abc21e10f1..13b9ad4f322 100644 --- a/litellm-rust/crates/lens/src/config.rs +++ b/litellm-rust/crates/lens/src/config.rs @@ -88,30 +88,6 @@ fn normalize_server_root_path(value: &str) -> Result { Ok(root.to_owned()) } -#[cfg(test)] -mod tests { - use super::normalize_server_root_path; - use rstest::rstest; - - #[rstest] - #[case::empty("", "")] - #[case::root("/", "")] - #[case::nested("/services/llm", "/services/llm")] - #[case::trailing_slash("/services/llm/", "/services/llm")] - fn normalizes_server_root_path(#[case] input: &str, #[case] expected: &str) { - assert_eq!(normalize_server_root_path(input).unwrap(), expected); - } - - #[rstest] - #[case::relative("relative")] - #[case::traversal("/a/../b")] - #[case::double_slash("/a//b")] - #[case::query("/a?b")] - fn rejects_unsafe_server_root_path(#[case] input: &str) { - assert!(normalize_server_root_path(input).is_err()); - } -} - fn clickhouse_url() -> Result { if let Ok(url) = required("CLICKHOUSE_URL") { return Ok(url); @@ -137,3 +113,27 @@ pub fn http_client() -> Result { ClientVariant::NoRedirect, )?) } + +#[cfg(test)] +mod tests { + use super::normalize_server_root_path; + use rstest::rstest; + + #[rstest] + #[case::empty("", "")] + #[case::root("/", "")] + #[case::nested("/services/llm", "/services/llm")] + #[case::trailing_slash("/services/llm/", "/services/llm")] + fn normalizes_server_root_path(#[case] input: &str, #[case] expected: &str) { + assert_eq!(normalize_server_root_path(input).unwrap(), expected); + } + + #[rstest] + #[case::relative("relative")] + #[case::traversal("/a/../b")] + #[case::double_slash("/a//b")] + #[case::query("/a?b")] + fn rejects_unsafe_server_root_path(#[case] input: &str) { + assert!(normalize_server_root_path(input).is_err()); + } +} From bbc43e9195cd7cb84cb39906e117ca9081bde096 Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 8 Oct 2026 14:14:27 +0200 Subject: [PATCH 09/13] fix(lens): preserve explicit ingress upload routes --- litellm-rust/crates/lens/src/lib.rs | 10 +++++++--- litellm-rust/crates/lens/tests/receiver.rs | 12 +++++++----- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/litellm-rust/crates/lens/src/lib.rs b/litellm-rust/crates/lens/src/lib.rs index 8f2a896d232..683503d9a3d 100644 --- a/litellm-rust/crates/lens/src/lib.rs +++ b/litellm-rust/crates/lens/src/lib.rs @@ -113,9 +113,13 @@ pub fn router_with_root_path(state: Arc, server_root_path: &str) -> Route http::header::CONTENT_ENCODING, ]), ); - public - .clone() - .nest(&format!("{server_root_path}/lens-ingest"), public) + let routes = public.clone().nest("/lens-ingest", public.clone()); + let routes = if server_root_path.is_empty() { + routes + } else { + routes.nest(&format!("{server_root_path}/lens-ingest"), public) + }; + routes .merge( Router::new() .route("/internal/read", post(read)) diff --git a/litellm-rust/crates/lens/tests/receiver.rs b/litellm-rust/crates/lens/tests/receiver.rs index 69ef14d7e18..d2fc3d454ae 100644 --- a/litellm-rust/crates/lens/tests/receiver.rs +++ b/litellm-rust/crates/lens/tests/receiver.rs @@ -327,11 +327,13 @@ async fn ingestion_confirms_storage_and_overwrites_exporter_tenant() { } #[rstest] -#[case::root("")] -#[case::nested("/services/llm")] +#[case::root("", "")] +#[case::shared("/services/llm", "/services/llm")] +#[case::explicit("/services/llm", "")] #[tokio::test] async fn shared_ingress_prefix_exposes_uploads_without_internal_control_routes( #[case] server_root_path: &str, + #[case] upload_root_path: &str, ) { let store = MockServer::start().await; Mock::given(method("POST")) @@ -343,7 +345,7 @@ async fn shared_ingress_prefix_exposes_uploads_without_internal_control_routes( let client = http_client().unwrap(); let upload = client .post(format!( - "{}{server_root_path}/lens-ingest/v1/traces", + "{}{upload_root_path}/lens-ingest/v1/traces", server.url )) .bearer_auth(KEY) @@ -360,7 +362,7 @@ async fn shared_ingress_prefix_exposes_uploads_without_internal_control_routes( assert_eq!(health.status(), 200); let internal = client .get(format!( - "{}{server_root_path}/lens-ingest/internal/status", + "{}{upload_root_path}/lens-ingest/internal/status", server.url )) .bearer_auth(SERVICE_TOKEN) @@ -371,7 +373,7 @@ async fn shared_ingress_prefix_exposes_uploads_without_internal_control_routes( let preflight = client .request( http::Method::OPTIONS, - format!("{}{server_root_path}/lens-ingest/v1/traces", server.url), + format!("{}{upload_root_path}/lens-ingest/v1/traces", server.url), ) .header("origin", "https://dashboard.example") .header("access-control-request-method", "POST") From aa7d2afa66e925e0d7dcd35e8d43e8466c8e6141 Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 15 Oct 2026 21:10:50 +0200 Subject: [PATCH 10/13] fix(ui): keep runtime backend discovery under the UI prefix --- .../src/components/networking.test.ts | 23 +++++++++++++++++++ .../src/components/networking.tsx | 5 +++- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/ui/litellm-dashboard/src/components/networking.test.ts b/ui/litellm-dashboard/src/components/networking.test.ts index dc582da6833..0b718bfae36 100644 --- a/ui/litellm-dashboard/src/components/networking.test.ts +++ b/ui/litellm-dashboard/src/components/networking.test.ts @@ -1038,6 +1038,29 @@ describe("getUiConfig runtime backend discovery", () => { return { networking, mockFetch }; }; + it("loads static runtime configuration from the UI prefix independently of the selected worker", async () => { + const mockFetch = vi + .fn() + .mockResolvedValueOnce({ + ok: true, + json: async () => ({ backend_url: "https://backend.example.com" }), + } as Response) + .mockResolvedValueOnce({ + ok: true, + json: async () => ({ ...discoveryConfig(), server_root_path: "/services/llm" }), + } as Response); + vi.stubGlobal("fetch", mockFetch); + const networking = await loadFreshNetworking(); + const { setServerRootPath } = await import("@/lib/serverRootPath"); + setServerRootPath("/services/llm"); + networking.switchToWorkerUrl("https://worker.example.com/worker-mount"); + + await networking.getUiConfig(); + + expect(mockFetch).toHaveBeenNthCalledWith(1, "/services/llm/ui/litellm-runtime-config.json", { cache: "no-store" }); + expect(mockFetch.mock.calls[1][0]).toBe("https://backend.example.com/litellm/.well-known/litellm-ui-config"); + }); + it("uses a normalized runtime backend URL for discovery and the management fallback", async () => { const mockFetch = vi .fn() diff --git a/ui/litellm-dashboard/src/components/networking.tsx b/ui/litellm-dashboard/src/components/networking.tsx index 2a2ce213216..9e68f1ad9a1 100644 --- a/ui/litellm-dashboard/src/components/networking.tsx +++ b/ui/litellm-dashboard/src/components/networking.tsx @@ -566,7 +566,10 @@ export const getUiConfig = async () => { : await (async (): Promise => { try { // eslint-disable-next-line no-restricted-syntax -- read the UI static config before the API origin is known - const response = await fetch("/ui/litellm-runtime-config.json", { cache: "no-store" }); + const response = await fetch( + `${serverRootPath === "/" ? "" : serverRootPath}/ui/litellm-runtime-config.json`, + { cache: "no-store" }, + ); if (!response.ok) return null; const runtimeConfig: unknown = await response.json(); if ( From 3cb875a4fa4fbc361b7f51ae93c568694e1cee3f Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 15 Oct 2026 21:28:01 +0200 Subject: [PATCH 11/13] fix(ui): resolve discovery paths before export preparation --- tests/integration/ui/test_ui_root_path.py | 2 +- .../src/components/networking.test.ts | 59 +++++++++++++------ .../src/components/networking.tsx | 3 +- ui/prepare-root-path.sh | 1 - 4 files changed, 45 insertions(+), 20 deletions(-) diff --git a/tests/integration/ui/test_ui_root_path.py b/tests/integration/ui/test_ui_root_path.py index d5d03619b5e..d2032bc8279 100644 --- a/tests/integration/ui/test_ui_root_path.py +++ b/tests/integration/ui/test_ui_root_path.py @@ -54,7 +54,7 @@ class TestUIRootPath(unittest.TestCase): self.assertIn("/services/llm/favicon.ico?version=1", (runtime / "index.txt").read_text()) self.assertEqual(runtime.stat().st_mode & 0o005, 0o005) self.assertEqual((runtime / "index.html").stat().st_mode & 0o004, 0o004) - self.assertIn("/services/llm/.well-known/litellm-ui-config", (runtime / "app.js").read_text()) + self.assertEqual((runtime / "app.js").read_bytes(), (source / "app.js").read_bytes()) self.assertEqual((source / "index.html").read_bytes(), original) self.assertEqual((runtime / "font.woff2").read_bytes(), (source / "font.woff2").read_bytes()) self.assertEqual(self.prepare(directory, "/services/llm/").returncode, 0) diff --git a/ui/litellm-dashboard/src/components/networking.test.ts b/ui/litellm-dashboard/src/components/networking.test.ts index 0b718bfae36..d55f79bf0a2 100644 --- a/ui/litellm-dashboard/src/components/networking.test.ts +++ b/ui/litellm-dashboard/src/components/networking.test.ts @@ -229,7 +229,7 @@ describe("UI config and public endpoints", () => { }; const mockFetch = setupMockFetch([ - { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }, + { url: "/.well-known/litellm-ui-config", data: uiConfig }, { url: "/public/providers/fields", data: [] }, ]); @@ -255,7 +255,7 @@ describe("UI config and public endpoints", () => { }; const mockFetch = setupMockFetch([ - { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }, + { url: "/.well-known/litellm-ui-config", data: uiConfig }, { url: "/public/model_hub/info", data: {} }, ]); @@ -278,7 +278,7 @@ describe("UI config and public endpoints", () => { }; const mockFetch = setupMockFetch([ - { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }, + { url: "/.well-known/litellm-ui-config", data: uiConfig }, { url: "/public/model_hub", data: [] }, ]); @@ -301,7 +301,7 @@ describe("UI config and public endpoints", () => { }; const mockFetch = setupMockFetch([ - { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }, + { url: "/.well-known/litellm-ui-config", data: uiConfig }, { url: "/public/agent_hub", data: [] }, ]); @@ -322,7 +322,7 @@ describe("UI config and public endpoints", () => { }; const mockFetch = setupMockFetch([ - { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }, + { url: "/.well-known/litellm-ui-config", data: uiConfig }, { url: "/public/mcp_hub", data: [] }, ]); @@ -343,7 +343,7 @@ describe("UI config and public endpoints", () => { }; const mockFetch = setupMockFetch([ - { url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }, + { url: "/.well-known/litellm-ui-config", data: uiConfig }, { url: "/public/providers/fields", data: [] }, ]); @@ -365,14 +365,14 @@ describe("UI config and public endpoints", () => { proxy_base_url: "https://example.com", }; - const mockFetch = setupMockFetch([{ url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }]); + const mockFetch = setupMockFetch([{ url: "/.well-known/litellm-ui-config", data: uiConfig }]); const result = await Networking.getUiConfig(); expect(mockFetch).toHaveBeenCalledTimes(2); expect(result).toEqual(uiConfig); const configCall = mockFetch.mock.calls.find((call) => - (call[0] as string).includes("/litellm/.well-known/litellm-ui-config"), + (call[0] as string).endsWith("/.well-known/litellm-ui-config"), ); expect(configCall).toBeDefined(); }); @@ -383,7 +383,7 @@ describe("UI config and public endpoints", () => { proxy_base_url: "https://example.com", }; - setupMockFetch([{ url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }]); + setupMockFetch([{ url: "/.well-known/litellm-ui-config", data: uiConfig }]); await Networking.getUiConfig(); @@ -397,7 +397,7 @@ describe("UI config and public endpoints", () => { proxy_base_url: "https://backend.example.com", gateway_base_url: "https://gateway.example.com", }; - const mockFetch = setupMockFetch([{ url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }]); + const mockFetch = setupMockFetch([{ url: "/.well-known/litellm-ui-config", data: uiConfig }]); await Networking.getUiConfig(); expect(await Networking.testModelGroupConnection("token", "chat-model", "chat")).toEqual({ status: "success" }); @@ -415,7 +415,7 @@ describe("UI config and public endpoints", () => { server_root_path: "", proxy_base_url: "https://backend.example.com", }; - const mockFetch = setupMockFetch([{ url: "/litellm/.well-known/litellm-ui-config", data: uiConfig }]); + const mockFetch = setupMockFetch([{ url: "/.well-known/litellm-ui-config", data: uiConfig }]); await Networking.getUiConfig(); expect(await Networking.testModelGroupConnection("token", "embedding-model", "embedding")).toEqual({ @@ -1038,13 +1038,38 @@ describe("getUiConfig runtime backend discovery", () => { return { networking, mockFetch }; }; - it("loads static runtime configuration from the UI prefix independently of the selected worker", async () => { + it.each(["https://backend.example.com", "https://backend.example.com/api-prefix"])( + "loads prefixed static configuration independently of the selected worker and API base %s", + async (backendBase) => { + const mockFetch = vi + .fn() + .mockResolvedValueOnce({ + ok: true, + json: async () => ({ backend_url: backendBase }), + } as Response) + .mockResolvedValueOnce({ + ok: true, + json: async () => ({ ...discoveryConfig(), server_root_path: "/services/llm" }), + } as Response); + vi.stubGlobal("fetch", mockFetch); + const networking = await loadFreshNetworking(); + const { setServerRootPath } = await import("@/lib/serverRootPath"); + setServerRootPath("/services/llm"); + networking.switchToWorkerUrl("https://worker.example.com/worker-mount"); + + await networking.getUiConfig(); + + expect(mockFetch).toHaveBeenNthCalledWith(1, "/services/llm/ui/litellm-runtime-config.json", { + cache: "no-store", + }); + expect(mockFetch.mock.calls[1][0]).toBe(`${backendBase}/litellm/.well-known/litellm-ui-config`); + }, + ); + + it("discovers the control plane under the UI prefix when no static backend is configured", async () => { const mockFetch = vi .fn() - .mockResolvedValueOnce({ - ok: true, - json: async () => ({ backend_url: "https://backend.example.com" }), - } as Response) + .mockResolvedValueOnce({ ok: false } as Response) .mockResolvedValueOnce({ ok: true, json: async () => ({ ...discoveryConfig(), server_root_path: "/services/llm" }), @@ -1058,7 +1083,7 @@ describe("getUiConfig runtime backend discovery", () => { await networking.getUiConfig(); expect(mockFetch).toHaveBeenNthCalledWith(1, "/services/llm/ui/litellm-runtime-config.json", { cache: "no-store" }); - expect(mockFetch.mock.calls[1][0]).toBe("https://backend.example.com/litellm/.well-known/litellm-ui-config"); + expect(mockFetch).toHaveBeenNthCalledWith(2, "/services/llm/.well-known/litellm-ui-config"); }); it("uses a normalized runtime backend URL for discovery and the management fallback", async () => { diff --git a/ui/litellm-dashboard/src/components/networking.tsx b/ui/litellm-dashboard/src/components/networking.tsx index 9e68f1ad9a1..2c247206b4b 100644 --- a/ui/litellm-dashboard/src/components/networking.tsx +++ b/ui/litellm-dashboard/src/components/networking.tsx @@ -587,9 +587,10 @@ export const getUiConfig = async () => { })(); runtimeBackendBaseUrl = runtimeBackendUrl; const discoveryBaseUrl = defaultProxyBaseUrl ?? runtimeBackendUrl; + const discoveryRoot = resolveApiBase({ serverRootPath }) || "/litellm"; const url = discoveryBaseUrl ? `${discoveryBaseUrl}/litellm/.well-known/litellm-ui-config` - : `/litellm/.well-known/litellm-ui-config`; + : `${discoveryRoot}/.well-known/litellm-ui-config`; const response = await fetch(url); const jsonData: LiteLLMWellKnownUiConfig = await response.json(); /** diff --git a/ui/prepare-root-path.sh b/ui/prepare-root-path.sh index bdd17e25840..c609c5422c3 100644 --- a/ui/prepare-root-path.sh +++ b/ui/prepare-root-path.sh @@ -29,7 +29,6 @@ if [ -n "$prefix" ]; then shift for file do sed -e "s|/litellm-asset-prefix|$prefix|g" \ - -e "s|/litellm/\.well-known/litellm-ui-config|$prefix/.well-known/litellm-ui-config|g" \ -e "s|/favicon.ico|$prefix/favicon.ico|g" \ "$file" > "$file.tmp" case "$file" in From 75a0f4265a8ebaec1242efd42c2513ee85f6a6e8 Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 15 Oct 2026 21:38:09 +0200 Subject: [PATCH 12/13] test(ui): gate authorization on prefixed configuration discovery --- .../useAuthorized.serverRootPath.test.ts | 22 +++++++++++++------ 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.serverRootPath.test.ts b/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.serverRootPath.test.ts index 228811ac37c..f294f9d880c 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.serverRootPath.test.ts +++ b/ui/litellm-dashboard/src/app/(dashboard)/hooks/useAuthorized.serverRootPath.test.ts @@ -1,6 +1,6 @@ /* @vitest-environment jsdom */ import React from "react"; -import { renderHook, waitFor } from "@testing-library/react"; +import { act, renderHook, waitFor } from "@testing-library/react"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import useAuthorized from "./useAuthorized"; @@ -9,8 +9,6 @@ vi.unmock("@/app/(dashboard)/hooks/useAuthorized"); const replaceMock = vi.fn(); -const UI_CONFIG_DELAY_MS = 50; - const uiConfigResponse = { server_root_path: "/llmproxy", proxy_base_url: null, @@ -19,13 +17,18 @@ const uiConfigResponse = { sso_configured: false, }; +let uiConfigGate = Promise.withResolvers(); + const fetchMock = vi.fn(async (input: RequestInfo | URL) => { const url = typeof input === "string" ? input : input.toString(); - if (!url.includes("/litellm/.well-known/litellm-ui-config")) { + if (url.endsWith("/ui/litellm-runtime-config.json")) { + return { ok: false } as Response; + } + if (!url.endsWith("/.well-known/litellm-ui-config")) { throw new Error(`unexpected fetch: ${url}`); } - await new Promise((resolve) => setTimeout(resolve, UI_CONFIG_DELAY_MS)); - return { ok: true, json: async () => uiConfigResponse } as unknown as Response; + const config = await uiConfigGate.promise; + return { ok: true, json: async () => config } as unknown as Response; }); const wrapper = ({ children }: { children: React.ReactNode }) => { @@ -37,6 +40,7 @@ describe("useAuthorized under SERVER_ROOT_PATH", () => { const originalLocation = window.location; beforeEach(() => { + uiConfigGate = Promise.withResolvers(); vi.stubGlobal("fetch", fetchMock); Object.defineProperty(window, "location", { value: { @@ -62,6 +66,7 @@ describe("useAuthorized under SERVER_ROOT_PATH", () => { it("sends an unauthenticated visitor to a login URL that keeps the server root path", async () => { renderHook(() => useAuthorized(), { wrapper }); + await act(async () => uiConfigGate.resolve(uiConfigResponse)); await waitFor(() => { expect(replaceMock).toHaveBeenCalled(); @@ -77,8 +82,11 @@ describe("useAuthorized under SERVER_ROOT_PATH", () => { renderHook(() => useAuthorized(), { wrapper }); expect(replaceMock).not.toHaveBeenCalled(); - await new Promise((resolve) => setTimeout(resolve, UI_CONFIG_DELAY_MS / 2)); + await waitFor(() => { + expect(fetchMock).toHaveBeenCalledWith(expect.stringMatching(/\/\.well-known\/litellm-ui-config$/)); + }); expect(replaceMock).not.toHaveBeenCalled(); + await act(async () => uiConfigGate.resolve(uiConfigResponse)); await waitFor(() => { expect(replaceMock).toHaveBeenCalled(); From c718c28d96a27a9612dbd1e601535746ee2b58a2 Mon Sep 17 00:00:00 2001 From: Martin Collado Date: Thu, 15 Oct 2026 22:00:03 +0200 Subject: [PATCH 13/13] fix(ui): normalize runtime configuration prefix --- .../src/components/networking.test.ts | 51 ++++++++++--------- .../src/components/networking.tsx | 8 +-- 2 files changed, 30 insertions(+), 29 deletions(-) diff --git a/ui/litellm-dashboard/src/components/networking.test.ts b/ui/litellm-dashboard/src/components/networking.test.ts index d55f79bf0a2..05fc77d40fc 100644 --- a/ui/litellm-dashboard/src/components/networking.test.ts +++ b/ui/litellm-dashboard/src/components/networking.test.ts @@ -1038,33 +1038,34 @@ describe("getUiConfig runtime backend discovery", () => { return { networking, mockFetch }; }; - it.each(["https://backend.example.com", "https://backend.example.com/api-prefix"])( - "loads prefixed static configuration independently of the selected worker and API base %s", - async (backendBase) => { - const mockFetch = vi - .fn() - .mockResolvedValueOnce({ - ok: true, - json: async () => ({ backend_url: backendBase }), - } as Response) - .mockResolvedValueOnce({ - ok: true, - json: async () => ({ ...discoveryConfig(), server_root_path: "/services/llm" }), - } as Response); - vi.stubGlobal("fetch", mockFetch); - const networking = await loadFreshNetworking(); - const { setServerRootPath } = await import("@/lib/serverRootPath"); - setServerRootPath("/services/llm"); - networking.switchToWorkerUrl("https://worker.example.com/worker-mount"); + it.each([ + ["https://backend.example.com", "/services/llm"], + ["https://backend.example.com/api-prefix", "/services/llm"], + ["https://backend.example.com", "/services/llm/"], + ])("loads static configuration from backend %s under normalized UI prefix %s", async (backendBase, uiPrefix) => { + const mockFetch = vi + .fn() + .mockResolvedValueOnce({ + ok: true, + json: async () => ({ backend_url: backendBase }), + } as Response) + .mockResolvedValueOnce({ + ok: true, + json: async () => ({ ...discoveryConfig(), server_root_path: "/services/llm" }), + } as Response); + vi.stubGlobal("fetch", mockFetch); + const networking = await loadFreshNetworking(); + const { setServerRootPath } = await import("@/lib/serverRootPath"); + setServerRootPath(uiPrefix); + networking.switchToWorkerUrl("https://worker.example.com/worker-mount"); - await networking.getUiConfig(); + await networking.getUiConfig(); - expect(mockFetch).toHaveBeenNthCalledWith(1, "/services/llm/ui/litellm-runtime-config.json", { - cache: "no-store", - }); - expect(mockFetch.mock.calls[1][0]).toBe(`${backendBase}/litellm/.well-known/litellm-ui-config`); - }, - ); + expect(mockFetch).toHaveBeenNthCalledWith(1, "/services/llm/ui/litellm-runtime-config.json", { + cache: "no-store", + }); + expect(mockFetch.mock.calls[1][0]).toBe(`${backendBase}/litellm/.well-known/litellm-ui-config`); + }); it("discovers the control plane under the UI prefix when no static backend is configured", async () => { const mockFetch = vi diff --git a/ui/litellm-dashboard/src/components/networking.tsx b/ui/litellm-dashboard/src/components/networking.tsx index 2c247206b4b..7eb60c464b3 100644 --- a/ui/litellm-dashboard/src/components/networking.tsx +++ b/ui/litellm-dashboard/src/components/networking.tsx @@ -156,6 +156,7 @@ import { registerBaseUrlGetter, registerErrorHandler, } from "@/lib/http/runtime"; +import { withServerRoot } from "@/lib/assetPaths"; import { serverRootPath, setServerRootPath } from "@/lib/serverRootPath"; export { serverRootPath }; @@ -566,10 +567,9 @@ export const getUiConfig = async () => { : await (async (): Promise => { try { // eslint-disable-next-line no-restricted-syntax -- read the UI static config before the API origin is known - const response = await fetch( - `${serverRootPath === "/" ? "" : serverRootPath}/ui/litellm-runtime-config.json`, - { cache: "no-store" }, - ); + const response = await fetch(withServerRoot("/ui/litellm-runtime-config.json", serverRootPath), { + cache: "no-store", + }); if (!response.ok) return null; const runtimeConfig: unknown = await response.json(); if (