This commit is contained in:
Martin Collado 2026-10-27 02:25:57 +00:00 • committed by GitHub
commit ce3b81edf8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
22 changed files with 510 additions and 40 deletions

View file

@ -1116,6 +1116,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/integration/ui -p test_ui_root_path.py
- name: Setup Node.js
if: steps.changes.outputs.decision != 'skip'
uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0

View file

@ -23,3 +23,73 @@ ui:
backend:
gatewayUrl: https://gateway.example.com
```
# 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 gateway, backend and UI 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
The prefix applies to gateway, backend and UI. Lens is distributed separately and keeps its independently configured ingestion 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
```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

View file

@ -698,6 +698,14 @@ shutdown drain window.
{{- 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 -}}
{{- define "litellm.lens.mode" -}}
{{- $mode := .Values.lensWorker.mode | default (ternary "bundled" "disabled" .Values.lensWorker.enabled) -}}
{{- if not (has $mode (list "bundled" "external" "disabled")) -}}

View file

@ -59,6 +59,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 }}
{{- if .Values.ui.publicUrl }}
- name: LITELLM_CORS_ORIGINS

View file

@ -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 }}
{{- if .Values.ui.publicUrl }}
- name: LITELLM_CORS_ORIGINS

View file

@ -32,6 +32,7 @@
{{- end }}
{{- end }}
{{- if .Values.ingress.enabled -}}
{{- $root := include "litellm.serverRootPath" . -}}
{{- $gatewayName := include "litellm.gateway.fullname" . -}}
{{- $backendName := include "litellm.backend.fullname" . -}}
{{- $uiName := include "litellm.ui.fullname" . -}}
@ -39,6 +40,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 }}
@ -77,6 +81,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 }}
@ -211,7 +218,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:
@ -224,14 +231,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:
@ -241,7 +248,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:
@ -293,7 +300,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:
@ -302,7 +309,7 @@ spec:
number: {{ $target.port }}
{{- end }}
# --- Catch-all → backend (management API: /key/*, /user/*, /team/*, ...) ---
- path: /
- path: {{ $root | default "/" }}
pathType: Prefix
backend:
service:

View file

@ -54,6 +54,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 }}

View file

@ -0,0 +1,74 @@
suite: custom server root path
templates:
- gateway/configmap.yaml
- 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

View file

@ -1,3 +1,5 @@
serverRootPath: ""
# LiteLLM helm chart values
nameOverride: ""
@ -198,7 +200,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: ""

View file

@ -0,0 +1,89 @@
import hashlib
import subprocess
import tempfile
import unittest
from pathlib import Path
from typing import Final
REPO: Final = Path(__file__).resolve().parents[3]
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(
'<html><head><link href="/get_favicon"><link href="/favicon.ico?version=1"></head><body>'
'<script src="/litellm-asset-prefix/_next/app.js"></script>'
'<img src="/ui/assets/logo.png"></body></html>'
)
(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
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('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.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)
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)

View file

@ -41,6 +41,11 @@ COPY ui/docker-entrypoint.d/40-litellm-runtime-config.sh /docker-entrypoint.d/
# 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

12
ui/docker-entrypoint.sh Normal file
View file

@ -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 "$@"

View file

@ -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<typeof uiConfigResponse>();
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<typeof uiConfigResponse>();
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();

View file

@ -1,6 +1,7 @@
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";
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<typeof vi.fn>).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);
});
});
@ -235,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<typeof vi.fn>).mockReturnValue({
data: {
auto_redirect_to_sso: false,
server_root_path: "/",
server_root_path: root,
proxy_base_url: null,
sso_configured: true,
},
@ -259,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 () => {

View file

@ -24,6 +24,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";
@ -108,7 +109,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;
}
@ -128,7 +129,7 @@ function LoginPageContent() {
if (returnUrl) {
router.replace(getUiPageUrl(returnUrl, true));
} else {
router.replace("/ui");
router.replace(uiHref("").replace(/\/$/, ""));
}
return;
}
@ -162,7 +163,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(getRuntimeBackendBaseUrl());
@ -344,7 +345,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"

View file

@ -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({
@ -1062,6 +1062,55 @@ describe("getUiConfig runtime backend discovery", () => {
return { networking, mockFetch };
};
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();
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: false } 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).toHaveBeenNthCalledWith(2, "/services/llm/.well-known/litellm-ui-config");
});
it("uses a normalized runtime backend URL for discovery and the management fallback", async () => {
const mockFetch = vi
.fn()

View file

@ -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,7 +567,9 @@ export const getUiConfig = async () => {
: await (async (): Promise<string | null> => {
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(withServerRoot("/ui/litellm-runtime-config.json", serverRootPath), {
cache: "no-store",
});
if (!response.ok) return null;
const runtimeConfig: unknown = await response.json();
if (
@ -584,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();
/**

View file

@ -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 = '<meta name="litellm-server-root-path" content="/services/llm">';
const { serverRootPath, setServerRootPath } = await import("./serverRootPath");
expect(serverRootPath).toBe("/services/llm");
setServerRootPath("/configured");
const updated = await import("./serverRootPath");
expect(updated.serverRootPath).toBe("/configured");
});
});

View file

@ -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<HTMLMetaElement>('meta[name="litellm-server-root-path"]')?.content || "/";
export const setServerRootPath = (rootPath: string): void => {
serverRootPath = rootPath;

View file

@ -1,5 +1,7 @@
// @vitest-environment jsdom
import { setServerRootPath } from "@/lib/serverRootPath";
import {
buildLoginUrlWithReturn,
clearStoredReturnUrl,
@ -37,6 +39,7 @@ describe("returnUrlUtils", () => {
});
afterEach(() => {
setServerRootPath("/");
// Restore original location
Object.defineProperty(window, "location", {
value: originalLocation,
@ -103,6 +106,24 @@ 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(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/");
});

View file

@ -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,8 @@ const RETURN_URL_COOKIE_NAME = "litellm_return_url";
const RETURN_URL_PARAM = "redirect_to";
export function getLoginUrl(baseUrl: string = ""): string {
return `${baseUrl}/ui/login/`;
const base = baseUrl.trim();
return `${base ? base.replace(/\/+$/, "") : resolveApiBase({ serverRootPath })}/ui/login/`;
}
export function normalizeBackendPageUrlToUiOrigin(

58
ui/prepare-root-path.sh Normal file
View file

@ -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|/favicon.ico|$prefix/favicon.ico|g" \
"$file" > "$file.tmp"
case "$file" in
*.html)
sed -e "s|<head>|<head><meta name=\"litellm-server-root-path\" content=\"$prefix\">|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