feat(basepath): add runtime env support for subpath deployments

datnguyennnx · datnguyennnx · commit 007bf4f0663c · 2025-09-27T16:19:10.000+07:00
diff --git a/.changeset/basepath-support.md b/.changeset/basepath-support.md
@@ -1,6 +1,7 @@
 ---
 '@hyperdx/app': minor
 '@hyperdx/api': minor
+'@hyperdx/common-utils': minor
 ---
 
 feat: Add basePath support for subpath deployments via environment variables
diff --git a/.env b/.env
@@ -20,9 +20,11 @@ HYPERDX_APP_PORT=8080
 HYPERDX_APP_URL=http://localhost
 HYPERDX_LOG_LEVEL=debug
 HYPERDX_OPAMP_PORT=4320
-HYPERDX_BASE_PATH=/hyperdx
-HYPERDX_API_BASE_PATH=/hyperdx/api
-HYPERDX_OTEL_BASE_PATH=/hyperdx/otel
+
+# Subpath support (leave empty for root)
+HYPERDX_BASE_PATH=
+HYPERDX_API_BASE_PATH=
+HYPERDX_OTEL_BASE_PATH=
 
 # Otel/Clickhouse config
 HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE=default
diff --git a/packages/api/src/api-app.ts b/packages/api/src/api-app.ts
@@ -1,3 +1,4 @@
+import { getApiBasePath } from '@hyperdx/common-utils/dist/basePath';
 import compression from 'compression';
 import MongoStore from 'connect-mongo';
 import express from 'express';
@@ -20,7 +21,7 @@ import passport from './utils/passport';
 
 const app: express.Application = express();
 
-const API_BASE_PATH = process.env.HYPERDX_API_BASE_PATH || '';
+const API_BASE_PATH = getApiBasePath();
 
 const sess: session.SessionOptions & { cookie: session.CookieOptions } = {
   resave: false,
@@ -83,10 +84,10 @@ if (config.USAGE_STATS_ENABLED) {
 // ---------------------------------------------------------------------
 if (API_BASE_PATH) {
   const apiRouter = express.Router();
-  
+
   // PUBLIC ROUTES
   apiRouter.use('/', routers.rootRouter);
-  
+
   // PRIVATE ROUTES
   apiRouter.use('/alerts', isUserAuthenticated, routers.alertsRouter);
   apiRouter.use('/dashboards', isUserAuthenticated, routers.dashboardRouter);
@@ -96,9 +97,13 @@ if (API_BASE_PATH) {
   apiRouter.use('/connections', isUserAuthenticated, connectionsRouter);
   apiRouter.use('/sources', isUserAuthenticated, sourcesRouter);
   apiRouter.use('/saved-search', isUserAuthenticated, savedSearchRouter);
-  apiRouter.use('/clickhouse-proxy', isUserAuthenticated, clickhouseProxyRouter);
+  apiRouter.use(
+    '/clickhouse-proxy',
+    isUserAuthenticated,
+    clickhouseProxyRouter,
+  );
   apiRouter.use('/api/v2', externalRoutersV2);
-  
+
   // Only initialize Swagger in development or if explicitly enabled
   if (
     process.env.NODE_ENV !== 'production' &&
@@ -116,7 +121,7 @@ if (API_BASE_PATH) {
         );
       });
   }
-  
+
   app.use(API_BASE_PATH, apiRouter);
 } else {
   // PUBLIC ROUTES
@@ -132,7 +137,7 @@ if (API_BASE_PATH) {
   app.use('/sources', isUserAuthenticated, sourcesRouter);
   app.use('/saved-search', isUserAuthenticated, savedSearchRouter);
   app.use('/clickhouse-proxy', isUserAuthenticated, clickhouseProxyRouter);
-  
+
   // TODO: Separate external API routers from internal routers
   // ---------------------------------------------------------------------
   // ----------------------- External Routers ----------------------------
diff --git a/packages/api/src/opamp/app.ts b/packages/api/src/opamp/app.ts
@@ -6,21 +6,19 @@ import { opampController } from '@/opamp/controllers/opampController';
 // Create Express application
 const app = express();
 
-const OTEL_BASE_PATH = process.env.HYPERDX_OTEL_BASE_PATH || '';
-
 app.disable('x-powered-by');
 
 // Special body parser setup for OpAMP
 app.use(
-  `${OTEL_BASE_PATH}/v1/opamp`,
+  '/v1/opamp',
   express.raw({
     type: 'application/x-protobuf',
     limit: '10mb',
   }),
 );
 
 // OpAMP endpoint
-app.post(`${OTEL_BASE_PATH}/v1/opamp`, opampController.handleOpampMessage.bind(opampController));
+app.post('/v1/opamp', opampController.handleOpampMessage.bind(opampController));
 
 // Health check endpoint
 app.get('/health', (req, res) => {
diff --git a/packages/app/next.config.js b/packages/app/next.config.js
@@ -1,5 +1,6 @@
 const { configureRuntimeEnv } = require('next-runtime-env/build/configure');
 const { version } = require('./package.json');
+const { getFrontendBasePath } = require('@hyperdx/common-utils/dist/basePath');
 
 configureRuntimeEnv();
 
@@ -9,7 +10,7 @@ const withNextra = require('nextra')({
 });
 
 module.exports = {
-  basePath: process.env.HYPERDX_BASE_PATH || '',
+  basePath: getFrontendBasePath(),
   experimental: {
     instrumentationHook: true,
     // External packages to prevent bundling issues with Next.js 14
@@ -58,8 +59,8 @@ module.exports = {
     productionBrowserSourceMaps: false,
     ...(process.env.NEXT_OUTPUT_STANDALONE === 'true'
       ? {
-        output: 'standalone',
-      }
+          output: 'standalone',
+        }
       : {}),
   }),
 };
diff --git a/packages/app/pages/_document.tsx b/packages/app/pages/_document.tsx
@@ -1,10 +1,11 @@
 import { Head, Html, Main, NextScript } from 'next/document';
+import { getFrontendBasePath } from '@hyperdx/common-utils/dist/basePath';
 
 export default function Document() {
   return (
     <Html lang="en">
       <Head>
-        <script src={`${process.env.HYPERDX_BASE_PATH || ''}/__ENV.js`} />
+        <script src={`${getFrontendBasePath()}/__ENV.js`} />
         <script src="https://cdn.jsdelivr.net/pyodide/v0.27.2/full/pyodide.js"></script>
         <link
           rel="stylesheet"
diff --git a/packages/app/pages/api/[...all].ts b/packages/app/pages/api/[...all].ts
@@ -1,8 +1,9 @@
 import { NextApiRequest, NextApiResponse } from 'next';
 import { createProxyMiddleware, fixRequestBody } from 'http-proxy-middleware';
+import { getApiBasePath } from '@hyperdx/common-utils/dist/basePath';
 
 const DEFAULT_SERVER_URL = `http://127.0.0.1:${process.env.HYPERDX_API_PORT}`;
-const API_BASE_PATH = process.env.HYPERDX_API_BASE_PATH || '';
+const API_BASE_PATH = getApiBasePath();
 
 export const config = {
   api: {
diff --git a/packages/app/src/api.ts b/packages/app/src/api.ts
@@ -2,6 +2,7 @@ import React from 'react';
 import Router from 'next/router';
 import type { HTTPError, Options, ResponsePromise } from 'ky';
 import ky from 'ky-universal';
+import { getApiBasePath } from '@hyperdx/common-utils/dist/basePath';
 import type { Alert } from '@hyperdx/common-utils/dist/types';
 import type { UseQueryOptions } from '@tanstack/react-query';
 import { useInfiniteQuery, useMutation, useQuery } from '@tanstack/react-query';
@@ -48,10 +49,7 @@ export function loginHook(request: Request, options: any, response: Response) {
 }
 
 // Get basePath from runtime environment
-const getApiPrefix = () => {
-  const basePath = process.env.HYPERDX_BASE_PATH || '';
-  return `${basePath}/api`;
-};
+const getApiPrefix = () => getApiBasePath();
 
 export const server = ky.create({
   prefixUrl: getApiPrefix(),
diff --git a/packages/app/src/clickhouse.ts b/packages/app/src/clickhouse.ts
@@ -5,6 +5,7 @@
 // please move app-specific functions elsewhere in the app
 // ================================
 
+import { getApiBasePath } from '@hyperdx/common-utils/dist/basePath';
 import {
   chSql,
   ClickhouseClientOptions,
@@ -20,7 +21,7 @@ import { getLocalConnections } from '@/connection';
 import api from './api';
 import { DEFAULT_QUERY_TIMEOUT } from './defaults';
 
-const PROXY_CLICKHOUSE_HOST = `${process.env.HYPERDX_BASE_PATH || ''}/api/clickhouse-proxy`;
+const PROXY_CLICKHOUSE_HOST = `${getApiBasePath()}/clickhouse-proxy`;
 
 export const getClickhouseClient = (
   options: ClickhouseClientOptions = {},
diff --git a/packages/common-utils/src/__tests__/basePath.test.ts b/packages/common-utils/src/__tests__/basePath.test.ts
@@ -0,0 +1,78 @@
+import {
+  getApiBasePath,
+  getFrontendBasePath,
+  getOtelBasePath,
+  joinPath,
+} from '../basePath';
+
+describe('basePath utilities', () => {
+  describe('getFrontendBasePath', () => {
+    it('returns empty string if no env var', () => {
+      delete process.env.HYPERDX_BASE_PATH;
+      expect(getFrontendBasePath()).toBe('');
+    });
+
+    it('returns normalized path for valid input', () => {
+      process.env.HYPERDX_BASE_PATH = '/hyperdx';
+      expect(getFrontendBasePath()).toBe('/hyperdx');
+
+      process.env.HYPERDX_BASE_PATH = 'hyperdx/';
+      expect(getFrontendBasePath()).toBe('/hyperdx');
+
+      process.env.HYPERDX_BASE_PATH = '/hyperdx/';
+      expect(getFrontendBasePath()).toBe('/hyperdx');
+    });
+
+    it('returns empty for invalid paths', () => {
+      process.env.HYPERDX_BASE_PATH = '/../invalid';
+      expect(getFrontendBasePath()).toBe('');
+
+      process.env.HYPERDX_BASE_PATH = 'http://example.com';
+      expect(getFrontendBasePath()).toBe('');
+    });
+  });
+
+  describe('getApiBasePath', () => {
+    it('defaults to /api if no env var', () => {
+      delete process.env.HYPERDX_API_BASE_PATH;
+      expect(getApiBasePath()).toBe('/api');
+    });
+
+    it('uses env var if set', () => {
+      process.env.HYPERDX_API_BASE_PATH = '/hyperdx/api';
+      expect(getApiBasePath()).toBe('/hyperdx/api');
+    });
+
+    it('normalizes input', () => {
+      process.env.HYPERDX_API_BASE_PATH = 'hyperdx/api/';
+      expect(getApiBasePath()).toBe('/hyperdx/api');
+    });
+  });
+
+  describe('getOtelBasePath', () => {
+    it('returns empty if no env var', () => {
+      delete process.env.HYPERDX_OTEL_BASE_PATH;
+      expect(getOtelBasePath()).toBe('');
+    });
+
+    it('returns normalized path', () => {
+      process.env.HYPERDX_OTEL_BASE_PATH = '/hyperdx/otel';
+      expect(getOtelBasePath()).toBe('/hyperdx/otel');
+    });
+  });
+
+  describe('joinPath', () => {
+    it('joins empty base with relative', () => {
+      expect(joinPath('', '/test')).toBe('/test');
+    });
+
+    it('joins valid base and relative', () => {
+      expect(joinPath('/hyperdx', '/api')).toBe('/hyperdx/api');
+      expect(joinPath('/hyperdx', 'api')).toBe('/hyperdx/api');
+    });
+
+    it('normalizes joined path', () => {
+      expect(joinPath('/hyperdx/', '/api/')).toBe('/hyperdx/api');
+    });
+  });
+});
diff --git a/packages/common-utils/src/basePath.ts b/packages/common-utils/src/basePath.ts
@@ -0,0 +1,82 @@
+import path from 'path';
+
+/**
+ * Normalizes a base path: ensures it starts with '/', removes trailing '/',
+ * and validates against common issues like path traversal or absolute URLs.
+ * @param basePath - The raw base path from env var
+ * @returns Normalized path or empty string if invalid
+ */
+function normalizeBasePath(basePath: string | undefined): string {
+  if (!basePath || typeof basePath !== 'string') {
+    return '';
+  }
+
+  const trimmed = basePath.trim();
+  if (!trimmed) {
+    return '';
+  }
+
+  // Validate: prevent full URLs on original trimmed input
+  if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+    console.warn(`Invalid base path detected: ${basePath}. Using empty path.`);
+    return '';
+  }
+
+  // Ensure leading slash
+  let normalized = trimmed;
+  if (!normalized.startsWith('/')) {
+    normalized = '/' + normalized;
+  }
+
+  // Remove trailing slash if present (except for root '/')
+  if (normalized.endsWith('/') && normalized !== '/') {
+    normalized = normalized.slice(0, -1);
+  }
+
+  // Validate: prevent path traversal
+  if (normalized.includes('..')) {
+    console.warn(`Invalid base path detected: ${basePath}. Using empty path.`);
+    return '';
+  }
+
+  return normalized;
+}
+
+/**
+ * Joins a base path with a relative path, normalizing the result.
+ * @param base - Normalized base path
+ * @param relative - Relative path to join
+ * @returns Full joined path
+ */
+export function joinPath(base: string, relative: string): string {
+  if (!base) return normalizeBasePath(relative);
+  if (!relative.startsWith('/')) relative = '/' + relative;
+  let joined = path.posix.join(base, relative);
+  if (!joined.startsWith('/')) joined = '/' + joined;
+  if (joined.endsWith('/') && joined !== '/') joined = joined.slice(0, -1);
+  return joined;
+}
+
+/**
+ * Gets the normalized frontend base path from HYPERDX_BASE_PATH env var.
+ */
+export function getFrontendBasePath(): string {
+  return normalizeBasePath(process.env.HYPERDX_BASE_PATH);
+}
+
+/**
+ * Gets the normalized API base path from HYPERDX_API_BASE_PATH env var.
+ * Defaults to '/api' if empty, but allows override.
+ */
+export function getApiBasePath(): string {
+  let apiPath = process.env.HYPERDX_API_BASE_PATH || '/api';
+  if (!apiPath.startsWith('/')) apiPath = '/' + apiPath;
+  return joinPath(normalizeBasePath(apiPath), '');
+}
+
+/**
+ * Gets the normalized OTEL base path from HYPERDX_OTEL_BASE_PATH env var.
+ */
+export function getOtelBasePath(): string {
+  return normalizeBasePath(process.env.HYPERDX_OTEL_BASE_PATH);
+}
diff --git a/proxy/nginx/nginx.conf b/proxy/nginx/nginx.conf
@@ -0,0 +1,37 @@
+server {
+  listen 80;
+  server_name localhost;
+
+  # Frontend
+  location /hyperdx/ {
+    rewrite ^/hyperdx/(.*) /$1 break;
+    proxy_pass http://app:8080;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";  # For WebSockets (live tailing)
+  }
+
+  # API
+  location /hyperdx/api/ {
+    rewrite ^/hyperdx/api/(.*) /api/$1 break;
+    proxy_pass http://app:8000;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+
+  # OTEL (adjust ports as needed)
+  location /hyperdx/otel/ {
+    rewrite ^/hyperdx/otel/(.*) /otel/$1 break;
+    proxy_pass http://otel-collector:4318;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+}
diff --git a/proxy/traefik/config.yml b/proxy/traefik/config.yml
