datahub/docs/deploy/BASE_PATH_CONFIGURATION.md

DataHub Base Path Configuration

This document describes how to configure DataHub to run from a custom base path (e.g., /my-app/ instead of /).

Overview

DataHub now supports serving from a custom base path, allowing you to:

• Serve DataHub from a subdirectory (e.g., https://company.com/datahub/)
• Deploy multiple DataHub instances on the same domain
• Integrate DataHub behind reverse proxies with path-based routing

Configuration

Environment Variables

Set the following environment variable to configure the base path:

export DATAHUB_BASE_PATH="/my-app"

Important Notes:

• The base path should start with / but not end with /
• Examples: /datahub, /my-app, /tools/datahub
• Leave empty or unset for root path deployment

Component Configuration

The base path configuration affects three main components:

1. Frontend (datahub-web-react)

The frontend determines the base path using multiple detection methods (in priority order):

1. Environment Variable (highest priority):

   # Set in .env file or environment
   REACT_APP_BASE_PATH=/my-app
   

2. Server Configuration (fetched from /config endpoint):

   • The React app fetches base path from the backend's configuration
   • Most reliable for production deployments

3. URL Analysis (fallback):

   • Analyzes current URL to detect base path
   • Used when server config is unavailable

Development Configuration:

# Method 1: Environment variable (recommended for development)
echo "REACT_APP_BASE_PATH=/my-app" >> .env
yarn start  # Development server at http://localhost:3000/my-app

# Method 2: Using Vite preview (for testing production builds)
yarn build
npx vite preview --port 3001  # Uses base path from REACT_APP_BASE_PATH
# Accessible at: http://localhost:3001/my-app

# Method 3: Override base path via command line
npx vite preview --port 3001 --base /custom-path

Production Behavior:

• Automatically fetches base path from server configuration
• Falls back to URL detection if server config unavailable
• Provides console warnings to help with debugging

2. DataHub Frontend Service (Play Framework)

The Play Framework application supports base path through:

• datahub.basePath configuration in application.conf
• play.http.context for Play Framework native support
• Environment variable: DATAHUB_BASE_PATH

3. Metadata Service (Spring Boot)

The metadata service (GMS) supports base path through:

• server.servlet.context-path in application.yaml
• Environment variable: DATAHUB_BASE_PATH

Deployment Examples

Docker Compose

version: "3.8"
services:
  datahub-frontend:
    environment:
      - DATAHUB_BASE_PATH=/datahub
	  - PLAY_HTTP_CONTEXT=/datahub

  datahub-gms:
    environment:
      - DATAHUB_BASE_PATH=/datahub

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: datahub-frontend
spec:
  template:
    spec:
      containers:
        - name: datahub-frontend
          env:
            - name: DATAHUB_BASE_PATH
              value: "/datahub"
            - name: DATAHUB_GMS_BASE_PATH
              value: "/datahub"
            - name: PLAY_HTTP_CONTEXT
              value: "/datahub"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: datahub-gms
spec:
  template:
    spec:
      containers:
        - name: datahub-frontend
          env:
            - name: DATAHUB_BASE_PATH
              value: "/datahub"
            - name: DATAHUB_GMS_BASE_PATH
              value: "/datahub"

Limitations

• Base path must be consistent across all DataHub components
• Changing base path requires restat of GMS and front end deployments.
• Testing of multiple DataHub environments served by the same URL, e.g. http://example.com/datahub1, http://example.com/datahub2, hasn't been extensively validated.