feat: removed plugin and serving the index.html only as the template

Restructure Validate nil check, rename expectErr to fail with
early-return, trim trailing newlines in test assertions, remove
t.Parallel from subtests, inline short config literals, restore
struct field comments in web.Config.

cmd/community/server.go

@@ -75,7 +75,7 @@ func runServer(ctx context.Context, config signoz.Config, logger *slog.Logger) e
 		},
 		signoz.NewEmailingProviderFactories(),
 		signoz.NewCacheProviderFactories(),
-		signoz.NewWebProviderFactories(),
+		signoz.NewWebProviderFactories(config.Global),
 		func(sqlstore sqlstore.SQLStore) factory.NamedMap[factory.ProviderFactory[sqlschema.SQLSchema, sqlschema.Config]] {
 			return signoz.NewSQLSchemaProviderFactories(sqlstore)
 		},

cmd/enterprise/server.go

@@ -96,7 +96,7 @@ func runServer(ctx context.Context, config signoz.Config, logger *slog.Logger) e
 		},
 		signoz.NewEmailingProviderFactories(),
 		signoz.NewCacheProviderFactories(),
-		signoz.NewWebProviderFactories(),
+		signoz.NewWebProviderFactories(config.Global),
 		func(sqlstore sqlstore.SQLStore) factory.NamedMap[factory.ProviderFactory[sqlschema.SQLSchema, sqlschema.Config]] {
 			existingFactories := signoz.NewSQLSchemaProviderFactories(sqlstore)
 			if err := existingFactories.Add(postgressqlschema.NewFactory(sqlstore)); err != nil {

conf/example.yaml

@@ -6,6 +6,8 @@
 ##################### Global #####################
 global:
   # the url under which the signoz apiserver is externally reachable.
+  # the path component (e.g. /signoz in https://example.com/signoz) is used
+  # as the base path for all HTTP routes (both API and web frontend).
   external_url: <unset>
   # the url where the SigNoz backend receives telemetry data (traces, metrics, logs) from instrumented applications.
   ingestion_url: <unset>
@@ -50,8 +52,8 @@ pprof:
 web:
   # Whether to enable the web frontend
   enabled: true
-  # The prefix to serve web on
-  prefix: /
+  # The index file to use as the SPA entrypoint.
+  index: index.html
   # The directory containing the static build files.
   directory: /etc/signoz/web
 

docs/contributing/onboarding.md

@@ -7,12 +7,12 @@ This guide explains how to add new data sources to the SigNoz onboarding flow. T
 The configuration is located at:
 
 ```
-frontend/src/container/OnboardingV2Container/onboarding-configs/onboarding-config-with-links.json
+frontend/src/container/OnboardingV2Container/onboarding-configs/onboarding-config-with-links.ts
 ```
 
-## JSON Structure Overview
+## Structure Overview
 
-The configuration file is a JSON array containing data source objects. Each object represents a selectable option in the onboarding flow.
+The configuration file exports a TypeScript array (`onboardingConfigWithLinks`) containing data source objects. Each object represents a selectable option in the onboarding flow. SVG logos are imported as ES modules at the top of the file.
 
 ## Data Source Object Keys
 
@@ -24,7 +24,7 @@ The configuration file is a JSON array containing data source objects. Each obje
 | `label` | `string` | Display name shown to users (e.g., `"AWS EC2"`) |
 | `tags` | `string[]` | Array of category tags for grouping (e.g., `["AWS"]`, `["database"]`) |
 | `module` | `string` | Destination module after onboarding completion |
-| `imgUrl` | `string` | Path to the logo/icon **(SVG required)** (e.g., `"/Logos/ec2.svg"`) |
+| `imgUrl` | `string` | Imported SVG URL **(SVG required)** (e.g., `import ec2Url from '@/assets/Logos/ec2.svg'`, then use `ec2Url`) |
 
 ### Optional Keys
 
@@ -57,36 +57,34 @@ The `module` key determines where users are redirected after completing onboardi
 
 The `question` object enables multi-step selection flows:
 
-```json
-{
-  "question": {
-    "desc": "What would you like to monitor?",
-    "type": "select",
-    "helpText": "Choose the telemetry type you want to collect.",
-    "helpLink": "/docs/azure-monitoring/overview/",
-    "helpLinkText": "Read the guide →",
-    "options": [
-        {
-            "key": "logging",
-            "label": "Logs",
-            "imgUrl": "/Logos/azure-vm.svg",
-            "link": "/docs/azure-monitoring/app-service/logging/"
-        },
-        {
-            "key": "metrics",
-            "label": "Metrics",
-            "imgUrl": "/Logos/azure-vm.svg",
-            "link": "/docs/azure-monitoring/app-service/metrics/"
-        },
-        {
-            "key": "tracing",
-            "label": "Traces",
-            "imgUrl": "/Logos/azure-vm.svg",
-            "link": "/docs/azure-monitoring/app-service/tracing/"
-        }
-    ]
-  }
-}
+```ts
+question: {
+  desc: 'What would you like to monitor?',
+  type: 'select',
+  helpText: 'Choose the telemetry type you want to collect.',
+  helpLink: '/docs/azure-monitoring/overview/',
+  helpLinkText: 'Read the guide →',
+  options: [
+    {
+      key: 'logging',
+      label: 'Logs',
+      imgUrl: azureVmUrl,
+      link: '/docs/azure-monitoring/app-service/logging/',
+    },
+    {
+      key: 'metrics',
+      label: 'Metrics',
+      imgUrl: azureVmUrl,
+      link: '/docs/azure-monitoring/app-service/metrics/',
+    },
+    {
+      key: 'tracing',
+      label: 'Traces',
+      imgUrl: azureVmUrl,
+      link: '/docs/azure-monitoring/app-service/tracing/',
+    },
+  ],
+},
 ```
 
 ### Question Keys
@@ -106,152 +104,161 @@ Options can be simple (direct link) or nested (with another question):
 
 ### Simple Option (Direct Link)
 
-```json
+```ts
 {
-  "key": "aws-ec2-logs",
-  "label": "Logs",
-  "imgUrl": "/Logos/ec2.svg",
-  "link": "/docs/userguide/collect_logs_from_file/"
-}
+  key: 'aws-ec2-logs',
+  label: 'Logs',
+  imgUrl: ec2Url,
+  link: '/docs/userguide/collect_logs_from_file/',
+},
 ```
 
 ### Option with Internal Redirect
 
-```json
+```ts
 {
-  "key": "aws-ec2-metrics-one-click",
-  "label": "One Click AWS",
-  "imgUrl": "/Logos/ec2.svg",
-  "link": "/integrations?integration=aws-integration&service=ec2",
-  "internalRedirect": true
-}
+  key: 'aws-ec2-metrics-one-click',
+  label: 'One Click AWS',
+  imgUrl: ec2Url,
+  link: '/integrations?integration=aws-integration&service=ec2',
+  internalRedirect: true,
+},
 ```
 
 > **Important**: Set `internalRedirect: true` only for internal app routes (like `/integrations?...`). Docs links should NOT have this flag.
 
 ### Nested Option (Multi-step Flow)
 
-```json
+```ts
 {
-  "key": "aws-ec2-metrics",
-  "label": "Metrics",
-  "imgUrl": "/Logos/ec2.svg",
-  "question": {
-    "desc": "How would you like to set up monitoring?",
-    "helpText": "Choose your setup method.",
-    "options": [...]
-  }
-}
+  key: 'aws-ec2-metrics',
+  label: 'Metrics',
+  imgUrl: ec2Url,
+  question: {
+    desc: 'How would you like to set up monitoring?',
+    helpText: 'Choose your setup method.',
+    options: [...],
+  },
+},
 ```
 
 ## Examples
 
 ### Simple Data Source (Direct Link)
 
-```json
+```ts
+import elbUrl from '@/assets/Logos/elb.svg';
+
+// inside the onboardingConfigWithLinks array:
 {
-  "dataSource": "aws-elb",
-  "label": "AWS ELB",
-  "tags": ["AWS"],
-  "module": "logs",
-  "relatedSearchKeywords": [
-    "aws",
-    "aws elb",
-    "elb logs",
-    "elastic load balancer"
+  dataSource: 'aws-elb',
+  label: 'AWS ELB',
+  tags: ['AWS'],
+  module: 'logs',
+  relatedSearchKeywords: [
+    'aws',
+    'aws elb',
+    'elb logs',
+    'elastic load balancer',
   ],
-  "imgUrl": "/Logos/elb.svg",
-  "link": "/docs/aws-monitoring/elb/"
-}
+  imgUrl: elbUrl,
+  link: '/docs/aws-monitoring/elb/',
+},
 ```
 
 ### Data Source with Single Question Level
 
-```json
+```ts
+import azureVmUrl from '@/assets/Logos/azure-vm.svg';
+
+// inside the onboardingConfigWithLinks array:
 {
-  "dataSource": "app-service",
-  "label": "App Service",
-  "imgUrl": "/Logos/azure-vm.svg",
-  "tags": ["Azure"],
-  "module": "apm",
-  "relatedSearchKeywords": ["azure", "app service"],
-  "question": {
-    "desc": "What telemetry data do you want to visualise?",
-    "type": "select",
-    "options": [
+  dataSource: 'app-service',
+  label: 'App Service',
+  imgUrl: azureVmUrl,
+  tags: ['Azure'],
+  module: 'apm',
+  relatedSearchKeywords: ['azure', 'app service'],
+  question: {
+    desc: 'What telemetry data do you want to visualise?',
+    type: 'select',
+    options: [
       {
-        "key": "logging",
-        "label": "Logs",
-        "imgUrl": "/Logos/azure-vm.svg",
-        "link": "/docs/azure-monitoring/app-service/logging/"
+        key: 'logging',
+        label: 'Logs',
+        imgUrl: azureVmUrl,
+        link: '/docs/azure-monitoring/app-service/logging/',
       },
       {
-        "key": "metrics",
-        "label": "Metrics",
-        "imgUrl": "/Logos/azure-vm.svg",
-        "link": "/docs/azure-monitoring/app-service/metrics/"
+        key: 'metrics',
+        label: 'Metrics',
+        imgUrl: azureVmUrl,
+        link: '/docs/azure-monitoring/app-service/metrics/',
       },
       {
-        "key": "tracing",
-        "label": "Traces",
-        "imgUrl": "/Logos/azure-vm.svg",
-        "link": "/docs/azure-monitoring/app-service/tracing/"
-      }
-    ]
-  }
-}
+        key: 'tracing',
+        label: 'Traces',
+        imgUrl: azureVmUrl,
+        link: '/docs/azure-monitoring/app-service/tracing/',
+      },
+    ],
+  },
+},
 ```
 
 ### Data Source with Nested Questions (2-3 Levels)
 
-```json
+```ts
+import ec2Url from '@/assets/Logos/ec2.svg';
+
+// inside the onboardingConfigWithLinks array:
 {
-  "dataSource": "aws-ec2",
-  "label": "AWS EC2",
-  "tags": ["AWS"],
-  "module": "logs",
-  "relatedSearchKeywords": ["aws", "aws ec2", "ec2 logs", "ec2 metrics"],
-  "imgUrl": "/Logos/ec2.svg",
-  "question": {
-    "desc": "What would you like to monitor for AWS EC2?",
-    "type": "select",
-    "helpText": "Choose the type of telemetry data you want to collect.",
-    "options": [
+  dataSource: 'aws-ec2',
+  label: 'AWS EC2',
+  tags: ['AWS'],
+  module: 'logs',
+  relatedSearchKeywords: ['aws', 'aws ec2', 'ec2 logs', 'ec2 metrics'],
+  imgUrl: ec2Url,
+  question: {
+    desc: 'What would you like to monitor for AWS EC2?',
+    type: 'select',
+    helpText: 'Choose the type of telemetry data you want to collect.',
+    options: [
       {
-        "key": "aws-ec2-logs",
-        "label": "Logs",
-        "imgUrl": "/Logos/ec2.svg",
-        "link": "/docs/userguide/collect_logs_from_file/"
+        key: 'aws-ec2-logs',
+        label: 'Logs',
+        imgUrl: ec2Url,
+        link: '/docs/userguide/collect_logs_from_file/',
       },
       {
-        "key": "aws-ec2-metrics",
-        "label": "Metrics",
-        "imgUrl": "/Logos/ec2.svg",
-        "question": {
-          "desc": "How would you like to set up EC2 Metrics monitoring?",
-          "helpText": "One Click uses AWS CloudWatch integration. Manual setup uses OpenTelemetry.",
-          "helpLink": "/docs/aws-monitoring/one-click-vs-manual/",
-          "helpLinkText": "Read the comparison guide →",
-          "options": [
+        key: 'aws-ec2-metrics',
+        label: 'Metrics',
+        imgUrl: ec2Url,
+        question: {
+          desc: 'How would you like to set up EC2 Metrics monitoring?',
+          helpText: 'One Click uses AWS CloudWatch integration. Manual setup uses OpenTelemetry.',
+          helpLink: '/docs/aws-monitoring/one-click-vs-manual/',
+          helpLinkText: 'Read the comparison guide →',
+          options: [
             {
-              "key": "aws-ec2-metrics-one-click",
-              "label": "One Click AWS",
-              "imgUrl": "/Logos/ec2.svg",
-              "link": "/integrations?integration=aws-integration&service=ec2",
-              "internalRedirect": true
+              key: 'aws-ec2-metrics-one-click',
+              label: 'One Click AWS',
+              imgUrl: ec2Url,
+              link: '/integrations?integration=aws-integration&service=ec2',
+              internalRedirect: true,
             },
             {
-              "key": "aws-ec2-metrics-manual",
-              "label": "Manual Setup",
-              "imgUrl": "/Logos/ec2.svg",
-              "link": "/docs/tutorial/opentelemetry-binary-usage-in-virtual-machine/"
-            }
-          ]
-        }
-      }
-    ]
-  }
-}
+              key: 'aws-ec2-metrics-manual',
+              label: 'Manual Setup',
+              imgUrl: ec2Url,
+              link: '/docs/tutorial/opentelemetry-binary-usage-in-virtual-machine/',
+            },
+          ],
+        },
+      },
+    ],
+  },
+},
 ```
 
 ## Best Practices
@@ -270,11 +277,16 @@ Options can be simple (direct link) or nested (with another question):
 
 ### 3. Logos
 
-- Place logo files in `public/Logos/`
+- Place logo files in `src/assets/Logos/`
 - Use SVG format
-- Reference as `"/Logos/your-logo.svg"`
+- Import the SVG at the top of the file and reference the imported variable:
+  ```ts
+  import myServiceUrl from '@/assets/Logos/my-service.svg';
+  // then in the config object:
+  imgUrl: myServiceUrl,
+  ```
 - **Fetching Icons**: New icons can be easily fetched from [OpenBrand](https://openbrand.sh/). Use the pattern `https://openbrand.sh/?url=<TARGET_URL>`, where `<TARGET_URL>` is the URL-encoded link to the service's website. For example, to get Render's logo, use [https://openbrand.sh/?url=https%3A%2F%2Frender.com](https://openbrand.sh/?url=https%3A%2F%2Frender.com).
-- **Optimize new SVGs**: Run any newly downloaded SVGs through an optimizer like [SVGOMG (svgo)](https://svgomg.net/) or use `npx svgo public/Logos/your-logo.svg` to minimise their size before committing.
+- **Optimize new SVGs**: Run any newly downloaded SVGs through an optimizer like [SVGOMG (svgo)](https://svgomg.net/) or use `npx svgo src/assets/Logos/your-logo.svg` to minimise their size before committing.
 
 ### 4. Links
 
@@ -290,8 +302,8 @@ Options can be simple (direct link) or nested (with another question):
 
 ## Adding a New Data Source
 
-1. Add your data source object to the JSON array
-2. Ensure the logo exists in `public/Logos/`
+1. Add the logo SVG to `src/assets/Logos/` and add a top-level import in the config file (e.g., `import myServiceUrl from '@/assets/Logos/my-service.svg'`)
+2. Add your data source object to the `onboardingConfigWithLinks` array, referencing the imported variable for `imgUrl`
 3. Test the flow locally with `yarn dev`
 4. Validation:
    - Navigate to the [onboarding page](http://localhost:3301/get-started-with-signoz-cloud) on your local machine

ee/query-service/app/server.go

@@ -262,6 +262,20 @@ func (s *Server) createPublicServer(apiHandler *api.APIHandler, web web.Web) (*h
 		return nil, err
 	}
 
+	routePrefix := s.config.Global.ExternalPath()
+	if routePrefix != "" {
+		prefixed := http.StripPrefix(routePrefix, handler)
+		handler = http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+			switch req.URL.Path {
+			case "/api/v1/health", "/api/v2/healthz", "/api/v2/readyz", "/api/v2/livez":
+				r.ServeHTTP(w, req)
+				return
+			}
+
+			prefixed.ServeHTTP(w, req)
+		})
+	}
+
 	return &http.Server{
 		Handler: handler,
 	}, nil

frontend/.gitignore

@@ -28,4 +28,7 @@ e2e/test-plan/saved-views/
 e2e/test-plan/service-map/
 e2e/test-plan/services/
 e2e/test-plan/traces/
-e2e/test-plan/user-preferences/
+e2e/test-plan/user-preferences/
+
+# Generated by `vite build` — do not commit
+index.html.gotmpl

frontend/index.html

@@ -2,6 +2,7 @@
 <html lang="en">
 	<head>
 		<meta charset="utf-8" />
+		<base href="[[.BasePath]]" />
 		<meta
 			http-equiv="Cache-Control"
 			content="no-cache, no-store, must-revalidate, max-age: 0"
@@ -59,7 +60,7 @@
 		<meta data-react-helmet="true" name="docusaurus_locale" content="en" />
 		<meta data-react-helmet="true" name="docusaurus_tag" content="default" />
 		<meta name="robots" content="noindex" />
-		<link data-react-helmet="true" rel="shortcut icon" href="/favicon.ico" />
+		<link data-react-helmet="true" rel="shortcut icon" href="favicon.ico" />
 	</head>
 	<body data-theme="default">
 		<noscript>You need to enable JavaScript to run this app.</noscript>
@@ -113,7 +114,7 @@
 				})(document, 'script');
 			}
 		</script>
-		<link rel="stylesheet" href="/css/uPlot.min.css" />
+		<link rel="stylesheet" href="css/uPlot.min.css" />
 		<script type="module" src="./src/index.tsx"></script>
 	</body>
 </html>

frontend/src/api/generatedAPIInstance.ts

@@ -1,5 +1,6 @@
 import {
 	interceptorRejected,
+	interceptorsRequestBasePath,
 	interceptorsRequestResponse,
 	interceptorsResponse,
 } from 'api';
@@ -17,6 +18,7 @@ export const GeneratedAPIInstance = <T>(
 	return generatedAPIAxiosInstance({ ...config }).then(({ data }) => data);
 };
 
+generatedAPIAxiosInstance.interceptors.request.use(interceptorsRequestBasePath);
 generatedAPIAxiosInstance.interceptors.request.use(interceptorsRequestResponse);
 generatedAPIAxiosInstance.interceptors.response.use(
 	interceptorsResponse,

frontend/src/api/index.ts

@@ -11,6 +11,7 @@ import axios, {
 import { ENVIRONMENT } from 'constants/env';
 import { Events } from 'constants/events';
 import { LOCALSTORAGE } from 'constants/localStorage';
+import { getBasePath } from 'utils/getBasePath';
 import { eventEmitter } from 'utils/getEventEmitter';
 
 import apiV1, { apiAlertManager, apiV2, apiV3, apiV4, apiV5 } from './apiV1';
@@ -67,6 +68,28 @@ export const interceptorsRequestResponse = (
 	return value;
 };
 
+// Prepends the runtime base path to outgoing requests so API calls work under
+// a URL prefix (e.g. /signoz/api/v1/…). No-op for root deployments and dev
+// (dev baseURL is a full http:// URL, not an absolute path).
+export const interceptorsRequestBasePath = (
+	value: InternalAxiosRequestConfig,
+): InternalAxiosRequestConfig => {
+	const basePath = getBasePath();
+	if (basePath === '/') {
+		return value;
+	}
+
+	if (value.baseURL?.startsWith('/')) {
+		// Named instances: baseURL='/api/v1/' → '/signoz/api/v1/'
+		value.baseURL = basePath + value.baseURL.slice(1);
+	} else if (!value.baseURL && value.url?.startsWith('/')) {
+		// Generated instance: baseURL is '' in prod, path is in url
+		value.url = basePath + value.url.slice(1);
+	}
+
+	return value;
+};
+
 export const interceptorRejected = async (
 	value: AxiosResponse<any>,
 ): Promise<AxiosResponse<any>> => {
@@ -133,6 +156,7 @@ const instance = axios.create({
 });
 
 instance.interceptors.request.use(interceptorsRequestResponse);
+instance.interceptors.request.use(interceptorsRequestBasePath);
 instance.interceptors.response.use(interceptorsResponse, interceptorRejected);
 
 export const AxiosAlertManagerInstance = axios.create({
@@ -147,6 +171,7 @@ ApiV2Instance.interceptors.response.use(
 	interceptorRejected,
 );
 ApiV2Instance.interceptors.request.use(interceptorsRequestResponse);
+ApiV2Instance.interceptors.request.use(interceptorsRequestBasePath);
 
 // axios V3
 export const ApiV3Instance = axios.create({
@@ -158,6 +183,7 @@ ApiV3Instance.interceptors.response.use(
 	interceptorRejected,
 );
 ApiV3Instance.interceptors.request.use(interceptorsRequestResponse);
+ApiV3Instance.interceptors.request.use(interceptorsRequestBasePath);
 //
 
 // axios V4
@@ -170,6 +196,7 @@ ApiV4Instance.interceptors.response.use(
 	interceptorRejected,
 );
 ApiV4Instance.interceptors.request.use(interceptorsRequestResponse);
+ApiV4Instance.interceptors.request.use(interceptorsRequestBasePath);
 //
 
 // axios V5
@@ -182,6 +209,7 @@ ApiV5Instance.interceptors.response.use(
 	interceptorRejected,
 );
 ApiV5Instance.interceptors.request.use(interceptorsRequestResponse);
+ApiV5Instance.interceptors.request.use(interceptorsRequestBasePath);
 //
 
 // axios Base
@@ -194,6 +222,7 @@ LogEventAxiosInstance.interceptors.response.use(
 	interceptorRejectedBase,
 );
 LogEventAxiosInstance.interceptors.request.use(interceptorsRequestResponse);
+LogEventAxiosInstance.interceptors.request.use(interceptorsRequestBasePath);
 //
 
 AxiosAlertManagerInstance.interceptors.response.use(
@@ -201,6 +230,7 @@ AxiosAlertManagerInstance.interceptors.response.use(
 	interceptorRejected,
 );
 AxiosAlertManagerInstance.interceptors.request.use(interceptorsRequestResponse);
+AxiosAlertManagerInstance.interceptors.request.use(interceptorsRequestBasePath);
 
 export { apiV1 };
 export default instance;

frontend/src/lib/history.ts

@@ -1,3 +1,4 @@
 import { createBrowserHistory } from 'history';
+import { getBasePath } from 'utils/getBasePath';
 
-export default createBrowserHistory();
+export default createBrowserHistory({ basename: getBasePath() });

frontend/src/pages/ErrorBoundaryFallback/ErrorBoundaryFallback.tsx

@@ -2,6 +2,7 @@ import { useCallback } from 'react';
 import { Button } from 'antd';
 import ROUTES from 'constants/routes';
 import { useGetTenantLicense } from 'hooks/useGetTenantLicense';
+import history from 'lib/history';
 import { Home, LifeBuoy } from 'lucide-react';
 import { handleContactSupport } from 'pages/Integrations/utils';
 
@@ -11,8 +12,9 @@ import './ErrorBoundaryFallback.styles.scss';
 
 function ErrorBoundaryFallback(): JSX.Element {
 	const handleReload = (): void => {
-		// Go to home page
-		window.location.href = ROUTES.HOME;
+		// Use history.push so the navigation stays within the base path prefix
+		// (window.location.href would strip any /signoz/ prefix).
+		history.push(ROUTES.HOME);
 	};
 
 	const { isCloudUser: isCloudUserVal } = useGetTenantLicense();

frontend/src/utils/__tests__/getBasePath.test.ts

@@ -0,0 +1,50 @@
+import { getBasePath } from 'utils/getBasePath';
+
+/**
+ * Contract tests for getBasePath().
+ *
+ * These lock down the exact DOM-reading contract so that any future change to
+ * the utility (or to how index.html injects the <base> tag) surfaces
+ * immediately as a test failure.
+ */
+describe('getBasePath', () => {
+	afterEach(() => {
+		// Remove any <base> elements added during the test.
+		document.head.querySelectorAll('base').forEach((el) => el.remove());
+	});
+
+	it('returns the href from the <base> tag when present', () => {
+		const base = document.createElement('base');
+		base.setAttribute('href', '/signoz/');
+		document.head.appendChild(base);
+
+		expect(getBasePath()).toBe('/signoz/');
+	});
+
+	it('returns "/" when no <base> tag exists in the document', () => {
+		expect(getBasePath()).toBe('/');
+	});
+
+	it('returns "/" when the <base> tag has no href attribute', () => {
+		const base = document.createElement('base');
+		document.head.appendChild(base);
+
+		expect(getBasePath()).toBe('/');
+	});
+
+	it('returns the href unchanged when it already has a trailing slash', () => {
+		const base = document.createElement('base');
+		base.setAttribute('href', '/my/nested/path/');
+		document.head.appendChild(base);
+
+		expect(getBasePath()).toBe('/my/nested/path/');
+	});
+
+	it('appends a trailing slash when the href is missing one', () => {
+		const base = document.createElement('base');
+		base.setAttribute('href', '/signoz');
+		document.head.appendChild(base);
+
+		expect(getBasePath()).toBe('/signoz/');
+	});
+});

frontend/src/utils/getBasePath.ts

@@ -0,0 +1,17 @@
+/**
+ * Returns the base path for this SigNoz deployment by reading the
+ * `<base href>` element injected into index.html by the Go backend at
+ * serve time.
+ *
+ * Always returns a string ending with `/` (e.g. `/`, `/signoz/`).
+ * Falls back to `/` when no `<base>` element is present so the app
+ * behaves correctly in local Vite dev and unit-test environments.
+ *
+ * @internal — consume through `src/lib/history` and the axios interceptor;
+ * do not read `<base>` directly anywhere else in the codebase.
+ */
+export function getBasePath(): string {
+	const href = document.querySelector('base')?.getAttribute('href') ?? '/';
+	// Trailing slash is required for relative asset resolution and API prefixing.
+	return href.endsWith('/') ? href : `${href}/`;
+}

frontend/vite.config.ts

@@ -10,6 +10,18 @@ import { createHtmlPlugin } from 'vite-plugin-html';
 import { ViteImageOptimizer } from 'vite-plugin-image-optimizer';
 import tsconfigPaths from 'vite-tsconfig-paths';
 
+// In dev the Go backend is not involved, so replace the [[.BasePath]] placeholder
+// with "/" so relative assets resolve correctly from the Vite dev server.
+function devBasePathPlugin(): Plugin {
+	return {
+		name: 'dev-base-path',
+		apply: 'serve',
+		transformIndexHtml(html): string {
+			return html.replace('[[.BasePath]]', '/');
+		},
+	};
+}
+
 function rawMarkdownPlugin(): Plugin {
 	return {
 		name: 'raw-markdown',
@@ -32,6 +44,7 @@ export default defineConfig(
 		const plugins = [
 			tsconfigPaths(),
 			rawMarkdownPlugin(),
+			devBasePathPlugin(),
 			react(),
 			createHtmlPlugin({
 				inject: {
@@ -124,6 +137,7 @@ export default defineConfig(
 				'process.env.TUNNEL_DOMAIN': JSON.stringify(env.VITE_TUNNEL_DOMAIN),
 				'process.env.DOCS_BASE_URL': JSON.stringify(env.VITE_DOCS_BASE_URL),
 			},
+			base: './',
 			build: {
 				sourcemap: true,
 				outDir: 'build',

pkg/global/config.go

@@ -2,6 +2,8 @@ package global
 
 import (
 	"net/url"
+	"path"
+	"strings"
 
 	"github.com/SigNoz/signoz/pkg/errors"
 
@@ -37,5 +39,34 @@ func newConfig() factory.Config {
 }
 
 func (c Config) Validate() error {
+	if c.ExternalURL != nil {
+		if c.ExternalURL.Path != "" && c.ExternalURL.Path != "/" {
+			if !strings.HasPrefix(c.ExternalURL.Path, "/") {
+				return errors.NewInvalidInputf(ErrCodeInvalidGlobalConfig, "global::external_url path must start with '/', got %q", c.ExternalURL.Path)
+			}
+		}
+	}
+
 	return nil
 }
+
+func (c Config) ExternalPath() string {
+	if c.ExternalURL == nil || c.ExternalURL.Path == "" || c.ExternalURL.Path == "/" {
+		return ""
+	}
+
+	p := path.Clean("/" + c.ExternalURL.Path)
+	if p == "/" {
+		return ""
+	}
+
+	return p
+}
+
+func (c Config) ExternalPathTrailing() string {
+	if p := c.ExternalPath(); p != "" {
+		return p + "/"
+	}
+
+	return "/"
+}

pkg/global/config_test.go

@@ -0,0 +1,139 @@
+package global
+
+import (
+	"net/url"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestExternalPath(t *testing.T) {
+	testCases := []struct {
+		name     string
+		config   Config
+		expected string
+	}{
+		{
+			name:     "NilURL",
+			config:   Config{ExternalURL: nil},
+			expected: "",
+		},
+		{
+			name:     "EmptyPath",
+			config:   Config{ExternalURL: &url.URL{Scheme: "https", Host: "example.com", Path: ""}},
+			expected: "",
+		},
+		{
+			name:     "RootPath",
+			config:   Config{ExternalURL: &url.URL{Scheme: "https", Host: "example.com", Path: "/"}},
+			expected: "",
+		},
+		{
+			name:     "SingleSegment",
+			config:   Config{ExternalURL: &url.URL{Scheme: "https", Host: "example.com", Path: "/signoz"}},
+			expected: "/signoz",
+		},
+		{
+			name:     "TrailingSlash",
+			config:   Config{ExternalURL: &url.URL{Scheme: "https", Host: "example.com", Path: "/signoz/"}},
+			expected: "/signoz",
+		},
+		{
+			name:     "MultiSegment",
+			config:   Config{ExternalURL: &url.URL{Scheme: "https", Host: "example.com", Path: "/a/b/c"}},
+			expected: "/a/b/c",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			assert.Equal(t, tc.expected, tc.config.ExternalPath())
+		})
+	}
+}
+
+func TestExternalPathTrailing(t *testing.T) {
+	testCases := []struct {
+		name     string
+		config   Config
+		expected string
+	}{
+		{
+			name:     "NilURL",
+			config:   Config{ExternalURL: nil},
+			expected: "/",
+		},
+		{
+			name:     "EmptyPath",
+			config:   Config{ExternalURL: &url.URL{Path: ""}},
+			expected: "/",
+		},
+		{
+			name:     "RootPath",
+			config:   Config{ExternalURL: &url.URL{Path: "/"}},
+			expected: "/",
+		},
+		{
+			name:     "SingleSegment",
+			config:   Config{ExternalURL: &url.URL{Path: "/signoz"}},
+			expected: "/signoz/",
+		},
+		{
+			name:     "MultiSegment",
+			config:   Config{ExternalURL: &url.URL{Path: "/a/b/c"}},
+			expected: "/a/b/c/",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			assert.Equal(t, tc.expected, tc.config.ExternalPathTrailing())
+		})
+	}
+}
+
+func TestValidate(t *testing.T) {
+	testCases := []struct {
+		name   string
+		config Config
+		fail   bool
+	}{
+		{
+			name:   "NilURL",
+			config: Config{ExternalURL: nil},
+			fail:   false,
+		},
+		{
+			name:   "EmptyPath",
+			config: Config{ExternalURL: &url.URL{Path: ""}},
+			fail:   false,
+		},
+		{
+			name:   "RootPath",
+			config: Config{ExternalURL: &url.URL{Path: "/"}},
+			fail:   false,
+		},
+		{
+			name:   "ValidPath",
+			config: Config{ExternalURL: &url.URL{Path: "/signoz"}},
+			fail:   false,
+		},
+		{
+			name:   "NoLeadingSlash",
+			config: Config{ExternalURL: &url.URL{Path: "signoz"}},
+			fail:   true,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			err := tc.config.Validate()
+			if tc.fail {
+				assert.Error(t, err)
+				return
+			}
+
+			assert.NoError(t, err)
+		})
+	}
+}

pkg/query-service/app/http_handler.go

@@ -587,7 +587,6 @@ func (aH *APIHandler) RegisterRoutes(router *mux.Router, am *middleware.AuthZ) {
 	router.HandleFunc("/api/v1/query_filter/analyze", am.ViewAccess(aH.QueryParserAPI.AnalyzeQueryFilter)).Methods(http.MethodPost)
 }
 
-
 func Intersection(a, b []int) (c []int) {
 	m := make(map[int]bool)
 

pkg/query-service/app/server.go

@@ -244,6 +244,20 @@ func (s *Server) createPublicServer(api *APIHandler, web web.Web) (*http.Server,
 		return nil, err
 	}
 
+	routePrefix := s.config.Global.ExternalPath()
+	if routePrefix != "" {
+		prefixed := http.StripPrefix(routePrefix, handler)
+		handler = http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+			switch req.URL.Path {
+			case "/api/v1/health", "/api/v2/healthz", "/api/v2/readyz", "/api/v2/livez":
+				r.ServeHTTP(w, req)
+				return
+			}
+
+			prefixed.ServeHTTP(w, req)
+		})
+	}
+
 	return &http.Server{
 		Handler: handler,
 	}, nil

pkg/signoz/provider.go

@@ -88,9 +88,9 @@ func NewCacheProviderFactories() factory.NamedMap[factory.ProviderFactory[cache.
 	)
 }
 
-func NewWebProviderFactories() factory.NamedMap[factory.ProviderFactory[web.Web, web.Config]] {
+func NewWebProviderFactories(globalConfig global.Config) factory.NamedMap[factory.ProviderFactory[web.Web, web.Config]] {
 	return factory.MustNewNamedMap(
-		routerweb.NewFactory(),
+		routerweb.NewFactory(globalConfig),
 		noopweb.NewFactory(),
 	)
 }

pkg/signoz/provider_test.go

@@ -8,6 +8,7 @@ import (
 	"github.com/SigNoz/signoz/pkg/alertmanager/nfmanager/nfmanagertest"
 	"github.com/SigNoz/signoz/pkg/analytics"
 	"github.com/SigNoz/signoz/pkg/flagger"
+	"github.com/SigNoz/signoz/pkg/global"
 	"github.com/SigNoz/signoz/pkg/instrumentation/instrumentationtest"
 	"github.com/SigNoz/signoz/pkg/modules/organization/implorganization"
 	"github.com/SigNoz/signoz/pkg/modules/user/impluser"
@@ -34,7 +35,7 @@ func TestNewProviderFactories(t *testing.T) {
 	})
 
 	assert.NotPanics(t, func() {
-		NewWebProviderFactories()
+		NewWebProviderFactories(global.Config{})
 	})
 
 	assert.NotPanics(t, func() {

pkg/web/config.go

@@ -8,10 +8,11 @@ import (
 type Config struct {
 	// Whether the web package is enabled.
 	Enabled bool `mapstructure:"enabled"`
-	// The prefix to serve the files from
-	Prefix string `mapstructure:"prefix"`
-	// The directory containing the static build files. The root of this directory should
-	// have an index.html file.
+
+	// The name of the index file to serve.
+	Index string `mapstructure:"index"`
+
+	// The directory from which to serve the web files.
 	Directory string `mapstructure:"directory"`
 }
 
@@ -22,7 +23,7 @@ func NewConfigFactory() factory.ConfigFactory {
 func newConfig() factory.Config {
 	return &Config{
 		Enabled:   true,
-		Prefix:    "/",
+		Index:     "index.html",
 		Directory: "/etc/signoz/web",
 	}
 }

pkg/web/config_test.go

@@ -12,7 +12,6 @@ import (
 )
 
 func TestNewWithEnvProvider(t *testing.T) {
-	t.Setenv("SIGNOZ_WEB_PREFIX", "/web")
 	t.Setenv("SIGNOZ_WEB_ENABLED", "false")
 
 	conf, err := config.New(
@@ -37,7 +36,7 @@ func TestNewWithEnvProvider(t *testing.T) {
 
 	expected := &Config{
 		Enabled:   false,
-		Prefix:    "/web",
+		Index:     def.Index,
 		Directory: def.Directory,
 	}
 

pkg/web/routerweb/provider.go

@@ -8,56 +8,55 @@ import (
 
 	"github.com/SigNoz/signoz/pkg/errors"
 	"github.com/SigNoz/signoz/pkg/factory"
+	"github.com/SigNoz/signoz/pkg/global"
 	"github.com/SigNoz/signoz/pkg/http/middleware"
 	"github.com/SigNoz/signoz/pkg/web"
 	"github.com/gorilla/mux"
 )
 
-const (
-	indexFileName string = "index.html"
-)
-
 type provider struct {
-	config web.Config
+	config        web.Config
+	indexContents []byte
+	fileHandler   http.Handler
 }
 
-func NewFactory() factory.ProviderFactory[web.Web, web.Config] {
-	return factory.NewProviderFactory(factory.MustNewName("router"), New)
+func NewFactory(globalConfig global.Config) factory.ProviderFactory[web.Web, web.Config] {
+	return factory.NewProviderFactory(factory.MustNewName("router"), func(ctx context.Context, settings factory.ProviderSettings, config web.Config) (web.Web, error) {
+		return New(ctx, settings, config, globalConfig)
+	})
 }
 
-func New(ctx context.Context, settings factory.ProviderSettings, config web.Config) (web.Web, error) {
+func New(ctx context.Context, settings factory.ProviderSettings, config web.Config, globalConfig global.Config) (web.Web, error) {
 	fi, err := os.Stat(config.Directory)
 	if err != nil {
 		return nil, errors.WrapInvalidInputf(err, errors.CodeInvalidInput, "cannot access web directory")
 	}
 
-	ok := fi.IsDir()
-	if !ok {
+	if !fi.IsDir() {
 		return nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "web directory is not a directory")
 	}
 
-	fi, err = os.Stat(filepath.Join(config.Directory, indexFileName))
+	indexPath := filepath.Join(config.Directory, config.Index)
+	raw, err := os.ReadFile(indexPath)
 	if err != nil {
-		return nil, errors.WrapInvalidInputf(err, errors.CodeInvalidInput, "cannot access %q in web directory", indexFileName)
+		return nil, errors.WrapInvalidInputf(err, errors.CodeInvalidInput, "cannot read %q in web directory", config.Index)
 	}
 
-	if os.IsNotExist(err) || fi.IsDir() {
-		return nil, errors.NewInvalidInputf(errors.CodeInvalidInput, "%q does not exist", indexFileName)
-	}
+	logger := factory.NewScopedProviderSettings(settings, "github.com/SigNoz/signoz/pkg/web/routerweb").Logger()
+	indexContents := web.NewIndex(ctx, logger, config.Index, raw, web.TemplateData{BaseHref: globalConfig.ExternalPathTrailing()})
 
 	return &provider{
-		config: config,
+		config:        config,
+		indexContents: indexContents,
+		fileHandler:   http.FileServer(http.Dir(config.Directory)),
 	}, nil
 }
 
 func (provider *provider) AddToRouter(router *mux.Router) error {
 	cache := middleware.NewCache(0)
-	err := router.PathPrefix(provider.config.Prefix).
+	err := router.PathPrefix("/").
 		Handler(
-			http.StripPrefix(
-				provider.config.Prefix,
-				cache.Wrap(http.HandlerFunc(provider.ServeHTTP)),
-			),
+			cache.Wrap(http.HandlerFunc(provider.ServeHTTP)),
 		).GetError()
 	if err != nil {
 		return errors.WrapInternalf(err, errors.CodeInternal, "unable to add web to router")
@@ -75,7 +74,7 @@ func (provider *provider) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 	if err != nil {
 		// if the file doesn't exist, serve index.html
 		if os.IsNotExist(err) {
-			http.ServeFile(rw, req, filepath.Join(provider.config.Directory, indexFileName))
+			provider.serveIndex(rw)
 			return
 		}
 
@@ -87,10 +86,15 @@ func (provider *provider) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
 
 	if fi.IsDir() {
 		// path is a directory, serve index.html
-		http.ServeFile(rw, req, filepath.Join(provider.config.Directory, indexFileName))
+		provider.serveIndex(rw)
 		return
 	}
 
 	// otherwise, use http.FileServer to serve the static file
-	http.FileServer(http.Dir(provider.config.Directory)).ServeHTTP(rw, req)
+	provider.fileHandler.ServeHTTP(rw, req)
+}
+
+func (provider *provider) serveIndex(rw http.ResponseWriter) {
+	rw.Header().Set("Content-Type", "text/html; charset=utf-8")
+	_, _ = rw.Write(provider.indexContents)
 }

pkg/web/routerweb/provider_test.go

@@ -5,45 +5,113 @@ import (
 	"io"
 	"net"
 	"net/http"
+	"net/url"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/SigNoz/signoz/pkg/factory/factorytest"
+	"github.com/SigNoz/signoz/pkg/global"
 	"github.com/SigNoz/signoz/pkg/web"
 	"github.com/gorilla/mux"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
-func TestServeHttpWithoutPrefix(t *testing.T) {
-	t.Parallel()
-	fi, err := os.Open(filepath.Join("testdata", indexFileName))
-	require.NoError(t, err)
+func startServer(t *testing.T, config web.Config, globalConfig global.Config) string {
+	t.Helper()
 
-	expected, err := io.ReadAll(fi)
-	require.NoError(t, err)
-
-	web, err := New(context.Background(), factorytest.NewSettings(), web.Config{Prefix: "/", Directory: filepath.Join("testdata")})
+	web, err := New(context.Background(), factorytest.NewSettings(), config, globalConfig)
 	require.NoError(t, err)
 
 	router := mux.NewRouter()
-	err = web.AddToRouter(router)
-	require.NoError(t, err)
+	require.NoError(t, web.AddToRouter(router))
 
 	listener, err := net.Listen("tcp", "localhost:0")
 	require.NoError(t, err)
 
-	server := &http.Server{
-		Handler: router,
+	server := &http.Server{Handler: router}
+	go func() { _ = server.Serve(listener) }()
+	t.Cleanup(func() { _ = server.Close() })
+
+	return "http://" + listener.Addr().String()
+}
+
+func httpGet(t *testing.T, url string) string {
+	t.Helper()
+
+	res, err := http.DefaultClient.Get(url)
+	require.NoError(t, err)
+	defer func() { _ = res.Body.Close() }()
+
+	body, err := io.ReadAll(res.Body)
+	require.NoError(t, err)
+
+	return string(body)
+}
+
+func TestServeTemplatedIndex(t *testing.T) {
+	t.Parallel()
+
+	testCases := []struct {
+		name         string
+		path         string
+		globalConfig global.Config
+		expected     string
+	}{
+		{
+			name:         "RootBaseHrefAtRoot",
+			path:         "/",
+			globalConfig: global.Config{},
+			expected:     `<html><head><base href="/" /></head><body>Welcome to test data!!!</body></html>`,
+		},
+		{
+			name:         "RootBaseHrefAtNonExistentPath",
+			path:         "/does-not-exist",
+			globalConfig: global.Config{},
+			expected:     `<html><head><base href="/" /></head><body>Welcome to test data!!!</body></html>`,
+		},
+		{
+			name:         "RootBaseHrefAtDirectory",
+			path:         "/assets",
+			globalConfig: global.Config{},
+			expected:     `<html><head><base href="/" /></head><body>Welcome to test data!!!</body></html>`,
+		},
+		{
+			name:         "SubPathBaseHrefAtRoot",
+			path:         "/",
+			globalConfig: global.Config{ExternalURL: &url.URL{Scheme: "https", Host: "example.com", Path: "/signoz"}},
+			expected:     `<html><head><base href="/signoz/" /></head><body>Welcome to test data!!!</body></html>`,
+		},
+		{
+			name:         "SubPathBaseHrefAtNonExistentPath",
+			path:         "/does-not-exist",
+			globalConfig: global.Config{ExternalURL: &url.URL{Scheme: "https", Host: "example.com", Path: "/signoz"}},
+			expected:     `<html><head><base href="/signoz/" /></head><body>Welcome to test data!!!</body></html>`,
+		},
+		{
+			name:         "SubPathBaseHrefAtDirectory",
+			path:         "/assets",
+			globalConfig: global.Config{ExternalURL: &url.URL{Scheme: "https", Host: "example.com", Path: "/signoz"}},
+			expected:     `<html><head><base href="/signoz/" /></head><body>Welcome to test data!!!</body></html>`,
+		},
 	}
 
-	go func() {
-		_ = server.Serve(listener)
-	}()
-	defer func() {
-		_ = server.Close()
-	}()
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			base := startServer(t, web.Config{Index: "valid_template.html", Directory: "testdata"}, testCase.globalConfig)
+
+			assert.Equal(t, testCase.expected, strings.TrimSuffix(httpGet(t, base+testCase.path), "\n"))
+		})
+	}
+}
+
+func TestServeNoTemplateIndex(t *testing.T) {
+	t.Parallel()
+
+	expected, err := os.ReadFile(filepath.Join("testdata", "no_template.html"))
+	require.NoError(t, err)
 
 	testCases := []struct {
 		name string
@@ -54,11 +122,7 @@ func TestServeHttpWithoutPrefix(t *testing.T) {
 			path: "/",
 		},
 		{
-			name: "Index",
-			path: "/" + indexFileName,
-		},
-		{
-			name: "DoesNotExist",
+			name: "NonExistentPath",
 			path: "/does-not-exist",
 		},
 		{
@@ -67,104 +131,55 @@ func TestServeHttpWithoutPrefix(t *testing.T) {
 		},
 	}
 
-	for _, tc := range testCases {
-		t.Run(tc.name, func(t *testing.T) {
-			res, err := http.DefaultClient.Get("http://" + listener.Addr().String() + tc.path)
-			require.NoError(t, err)
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			base := startServer(t, web.Config{Index: "no_template.html", Directory: "testdata"}, global.Config{})
 
-			defer func() {
-				_ = res.Body.Close()
-			}()
-
-			actual, err := io.ReadAll(res.Body)
-			require.NoError(t, err)
-
-			assert.Equal(t, expected, actual)
+			assert.Equal(t, string(expected), httpGet(t, base+testCase.path))
 		})
 	}
-
 }
 
-func TestServeHttpWithPrefix(t *testing.T) {
+func TestServeInvalidTemplateIndex(t *testing.T) {
 	t.Parallel()
-	fi, err := os.Open(filepath.Join("testdata", indexFileName))
+
+	expected, err := os.ReadFile(filepath.Join("testdata", "invalid_template.html"))
 	require.NoError(t, err)
 
-	expected, err := io.ReadAll(fi)
-	require.NoError(t, err)
-
-	web, err := New(context.Background(), factorytest.NewSettings(), web.Config{Prefix: "/web", Directory: filepath.Join("testdata")})
-	require.NoError(t, err)
-
-	router := mux.NewRouter()
-	err = web.AddToRouter(router)
-	require.NoError(t, err)
-
-	listener, err := net.Listen("tcp", "localhost:0")
-	require.NoError(t, err)
-
-	server := &http.Server{
-		Handler: router,
-	}
-
-	go func() {
-		_ = server.Serve(listener)
-	}()
-	defer func() {
-		_ = server.Close()
-	}()
-
 	testCases := []struct {
-		name  string
-		path  string
-		found bool
+		name string
+		path string
 	}{
 		{
-			name:  "Root",
-			path:  "/web",
-			found: true,
+			name: "Root",
+			path: "/",
 		},
 		{
-			name:  "Index",
-			path:  "/web/" + indexFileName,
-			found: true,
+			name: "NonExistentPath",
+			path: "/does-not-exist",
 		},
 		{
-			name:  "FileDoesNotExist",
-			path:  "/web/does-not-exist",
-			found: true,
-		},
-		{
-			name:  "Directory",
-			path:  "/web/assets",
-			found: true,
-		},
-		{
-			name:  "DoesNotExist",
-			path:  "/does-not-exist",
-			found: false,
+			name: "Directory",
+			path: "/assets",
 		},
 	}
 
-	for _, tc := range testCases {
-		t.Run(tc.name, func(t *testing.T) {
-			res, err := http.DefaultClient.Get("http://" + listener.Addr().String() + tc.path)
-			require.NoError(t, err)
-
-			defer func() {
-				_ = res.Body.Close()
-			}()
-
-			if tc.found {
-				actual, err := io.ReadAll(res.Body)
-				require.NoError(t, err)
-
-				assert.Equal(t, expected, actual)
-			} else {
-				assert.Equal(t, http.StatusNotFound, res.StatusCode)
-			}
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			base := startServer(t, web.Config{Index: "invalid_template.html", Directory: "testdata"}, global.Config{ExternalURL: &url.URL{Path: "/signoz"}})
 
+			assert.Equal(t, string(expected), httpGet(t, base+testCase.path))
 		})
 	}
-
+}
+
+func TestServeStaticFilesUnchanged(t *testing.T) {
+	t.Parallel()
+
+	expected, err := os.ReadFile(filepath.Join("testdata", "assets", "style.css"))
+	require.NoError(t, err)
+
+	base := startServer(t, web.Config{Index: "valid_template.html", Directory: "testdata"}, global.Config{ExternalURL: &url.URL{Path: "/signoz"}})
+
+	assert.Equal(t, string(expected), httpGet(t, base+"/assets/style.css"))
 }

pkg/web/routerweb/testdata/assets/index.css

@@ -1,3 +0,0 @@
-#root {
-  background-color: red;
-}

pkg/web/routerweb/testdata/assets/style.css

@@ -0,0 +1 @@
+body { color: red; }

pkg/web/routerweb/testdata/index.html

@@ -1 +0,0 @@
-<h1>Welcome to test data!!!</h1>

pkg/web/routerweb/testdata/invalid_template.html

@@ -0,0 +1 @@
+<html><head><base href="[[." /></head><body>Bad template</body></html>

pkg/web/routerweb/testdata/no_template.html

@@ -0,0 +1 @@
+<html><head></head><body>No template here</body></html>

pkg/web/routerweb/testdata/valid_template.html

@@ -0,0 +1 @@
+<html><head><base href="[[.BaseHref]]" /></head><body>Welcome to test data!!!</body></html>

pkg/web/template.go

@@ -0,0 +1,42 @@
+package web
+
+import (
+	"bytes"
+	"context"
+	"log/slog"
+	"text/template"
+
+	"github.com/SigNoz/signoz/pkg/errors"
+)
+
+// Field names map to the HTML attributes they populate in the template:
+//   - BaseHref  → <base href="[[.BaseHref]]" />
+type TemplateData struct {
+	BaseHref string
+}
+
+// If the template cannot be parsed or executed, the raw bytes are
+// returned unchanged and the error is logged.
+func NewIndex(ctx context.Context, logger *slog.Logger, name string, raw []byte, data TemplateData) []byte {
+	result, err := NewIndexE(name, raw, data)
+	if err != nil {
+		logger.ErrorContext(ctx, "cannot render index template, serving raw file", slog.String("name", name), errors.Attr(err))
+		return raw
+	}
+
+	return result
+}
+
+func NewIndexE(name string, raw []byte, data TemplateData) ([]byte, error) {
+	tmpl, err := template.New(name).Delims("[[", "]]").Parse(string(raw))
+	if err != nil {
+		return nil, errors.WrapInvalidInputf(err, errors.CodeInvalidInput, "cannot parse %q as template", name)
+	}
+
+	var buf bytes.Buffer
+	if err := tmpl.Execute(&buf, data); err != nil {
+		return nil, errors.WrapInvalidInputf(err, errors.CodeInvalidInput, "cannot execute template for %q", name)
+	}
+
+	return buf.Bytes(), nil
+}