feat: basePath

Author: jona7o

Dockerfile

@@ -28,12 +28,16 @@ RUN npm run build
 FROM node:22-alpine AS runner
 WORKDIR /app
 
+# Re-declare ARG to make it available in this stage
+ARG NEXT_PUBLIC_BASE_PATH=""
+
 RUN apk update && apk upgrade && rm -rf /var/cache/apk/* \
     && addgroup --system --gid 1001 nodejs \
     && adduser --system --uid 1001 nextjs
 
 ENV NODE_ENV=production
 ENV NEXT_TELEMETRY_DISABLED=1
+ENV NEXT_PUBLIC_BASE_PATH=${NEXT_PUBLIC_BASE_PATH}
 
 COPY --from=builder /app/public ./public
 COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
@@ -44,7 +48,8 @@ EXPOSE 3000
 ENV PORT=3000
 ENV HOSTNAME="0.0.0.0"
 
+# Healthcheck uses the basePath for the health endpoint
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
+    CMD wget --no-verbose --tries=1 --spider http://localhost:3000${NEXT_PUBLIC_BASE_PATH}/api/health || exit 1
 
 CMD ["node", "server.js"]

README.md

@@ -58,15 +58,52 @@ docker run -p 3000:3000 \
 | `SESSION_SECRET` | No | Session signing secret (auto-generated) |
 | `NEXT_PUBLIC_BASE_PATH` | No | Base path for reverse proxy (e.g., `/dashboard`) |
 
-## Reverse Proxy
+## Reverse Proxy / Kubernetes Ingress
+
+The official Docker images are built with `NEXT_PUBLIC_BASE_PATH=/dashboard`, meaning the app expects to run under the `/dashboard` path.
+
+### Kubernetes Ingress Example
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: dashboard-ingress
+spec:
+  rules:
+  - host: your-domain.com
+    http:
+      paths:
+      - path: /dashboard
+        pathType: Prefix
+        backend:
+          service:
+            name: dashboard-service
+            port:
+              number: 3000
+```
+
+No `rewrite-target` annotation is needed since the app already expects requests at `/dashboard`.
+
+### Custom Base Path
+
+To use a different base path, rebuild the Docker image:
+
+```bash
+docker build --build-arg NEXT_PUBLIC_BASE_PATH=/your-path -t librechat-dashboard .
+```
+
+### Local Development
 
-To deploy under a sub-path (e.g., `/dashboard`):
+For local development without a base path, simply run:
 
 ```bash
-docker build --build-arg NEXT_PUBLIC_BASE_PATH=/dashboard -t librechat-dashboard .
+npm run dev
 ```
 
-> **Note**: `NEXT_PUBLIC_BASE_PATH` is baked into the build. Rebuild when changing.
+The app will be available at `http://localhost:3000` (without any path prefix).
+
+> **Note**: `NEXT_PUBLIC_BASE_PATH` is baked into the build at compile time. You must rebuild when changing this value.
 
 ## Development Commands
 

next.config.ts

@@ -1,11 +1,11 @@
 import type { NextConfig } from "next";
 
-const basePath = process.env.NEXT_PUBLIC_BASE_PATH || "/dashboard";
+const basePath = process.env.NEXT_PUBLIC_BASE_PATH || "";
 
 const nextConfig: NextConfig = {
 	output: "standalone",
-	basePath: basePath,
-	assetPrefix: basePath,
+	basePath: basePath.length > 0 ? basePath : undefined,
+	assetPrefix: basePath.length > 0 ? basePath : undefined,
 	poweredByHeader: false,
 	reactStrictMode: true,
 	images: {
@@ -33,15 +33,6 @@ const nextConfig: NextConfig = {
 			},
 		];
 	},
-	async redirects() {
-		return [
-			{
-				source: "/",
-				destination: "/dashboard",
-				permanent: false,
-			},
-		];
-	},
 };
 
 export default nextConfig;

src/app/login/page.tsx

@@ -14,6 +14,7 @@ import {
 } from "@mui/material";
 import { useTheme } from "@mui/material/styles";
 import { type FormEvent, useCallback, useState } from "react";
+import { API_BASE, getAbsolutePath } from "@/lib/utils/api-base";
 
 export default function LoginPage() {
 	const [password, setPassword] = useState("");
@@ -32,7 +33,7 @@ export default function LoginPage() {
 			setIsLoading(true);
 
 			try {
-				const response = await fetch("/api/auth/login", {
+				const response = await fetch(`${API_BASE}/auth/login`, {
 					method: "POST",
 					headers: {
 						"Content-Type": "application/json",
@@ -44,7 +45,7 @@ export default function LoginPage() {
 				if (response.ok) {
 					setPassword(""); // Clear password from memory
 					// Force a full page reload to reset AuthGuard state
-					window.location.href = "/dashboard/dashboard";
+					window.location.href = getAbsolutePath("/dashboard");
 				} else {
 					const data = await response.json();
 					setError(data.error || "Authentication failed. Please try again.");

src/app/page.tsx

@@ -1,8 +1,9 @@
 import { redirect } from "next/navigation";
 
 export default function RootPage() {
-	// When basePath is set to /dashboard, this page will be at /dashboard
-	// Redirect to /dashboard/dashboard for consistency, but next.config.ts
-	// already handles / -> /dashboard redirect
+	// Redirect to the dashboard page
+	// Next.js router automatically applies basePath, so "/dashboard" becomes:
+	// - "/dashboard" when no basePath is set (local dev)
+	// - "/dashboard/dashboard" when basePath="/dashboard" (Docker/production)
 	redirect("/dashboard");
 }

src/atoms/active-users-atom.tsx

@@ -1,9 +1,8 @@
 import { atom } from "jotai";
 import type { ActiveUsers } from "@/components/models/active-users";
+import { API_BASE } from "@/lib/utils/api-base";
 import { dateRangeAtom } from "./date-range-atom";
 
-const API_BASE = process.env.NEXT_PUBLIC_API_BACKEND_BASE_URL_NODE || "/api";
-
 export const activeUsersAtom = atom(async (get) => {
 	const timeArea = get(dateRangeAtom);
 	const res = await fetch(

src/atoms/agent-count-atom.tsx

@@ -1,7 +1,6 @@
 import { atom } from "jotai";
 import type { AgentCount } from "@/components/models/agent-count";
-
-const API_BASE = process.env.NEXT_PUBLIC_API_BACKEND_BASE_URL_NODE || "/api";
+import { API_BASE } from "@/lib/utils/api-base";
 
 export const agentCountAtom = atom(async () => {
 	const res = await fetch(`${API_BASE}/all-agents`);

src/atoms/all-agents-stats-table-atom.tsx

@@ -1,9 +1,8 @@
 import { atom } from "jotai";
 import type { AllAgentsStatsTable } from "@/components/models/all-agents-stats-table";
+import { API_BASE } from "@/lib/utils/api-base";
 import { dateRangeAtom } from "./date-range-atom";
 
-const API_BASE = process.env.NEXT_PUBLIC_API_BACKEND_BASE_URL_NODE || "/api";
-
 export const allAgentsStatsTableAtom = atom(async (get) => {
 	const timeArea = get(dateRangeAtom);
 	const res = await fetch(

src/atoms/all-agents-stats-table-chart.atom.tsx

@@ -2,10 +2,9 @@ import { atom } from "jotai";
 import { atomFamily } from "jotai/utils";
 import type { AllAgentsStatsChart } from "@/components/models/all-agents-stats-chart";
 import { timeMap } from "@/components/utils/time-map";
+import { API_BASE } from "@/lib/utils/api-base";
 import { dateRangeAtom } from "./date-range-atom";
 
-const API_BASE = process.env.NEXT_PUBLIC_API_BACKEND_BASE_URL_NODE || "/api";
-
 export const allAgentsStatsTableChartAtom = atomFamily((agent: string) =>
 	atom(async (get) => {
 		const timeArea = get(dateRangeAtom);

src/atoms/all-models-stats-table-atom.tsx

@@ -1,9 +1,8 @@
 import { atom } from "jotai";
 import type { AllModelsStatsTable } from "@/components/models/all-models-stats-table";
+import { API_BASE } from "@/lib/utils/api-base";
 import { dateRangeAtom } from "./date-range-atom";
 
-const API_BASE = process.env.NEXT_PUBLIC_API_BACKEND_BASE_URL_NODE || "/api";
-
 export const allModelsStatsTableAtom = atom(async (get) => {
 	const timeArea = get(dateRangeAtom);
 	const res = await fetch(