How to Configure the OpenMetadata UI for Development

Start the OpenMetadata UI development environment by running yarn install and yarn start from the openmetadata-ui/src/main/resources/ui directory, with the backend API running on http://localhost:8585.

The OpenMetadata UI is a React-based TypeScript application that provides the primary interface for metadata discovery, data governance, and collaboration. Configuring the OpenMetadata UI for development requires setting up the Node.js environment, connecting to a running backend API, and understanding the local development workflow. This guide walks through the complete setup process based on the actual source code structure in open-metadata/OpenMetadata.

---

Prerequisites for OpenMetadata UI Development

Before configuring the UI, ensure your system meets the following requirements:

Tool	Minimum Version	Purpose
Node.js	18.x	JavaScript runtime for React build
Yarn	1.22.x	Package manager (classic version)
Docker & Docker Compose	2.20+	Backend services (MySQL, Elasticsearch, API)

The UI source code resides in openmetadata-ui/src/main/resources/ui/, which follows a standard React project structure with custom OpenMetadata components.

---

Step 1: Install UI Dependencies

Navigate to the UI directory and install all required packages:

cd openmetadata-ui/src/main/resources/ui

yarn install

This command reads package.json and installs approximately 2,000+ dependencies including React 18, TypeScript 4.x, Ant Design, and OpenMetadata's internal component libraries. The yarn.lock file ensures reproducible builds across environments.

---

Step 2: Configure the Backend API Connection

The UI expects the OpenMetadata backend API running at http://localhost:8585. Ensure your backend is active:

# From repository root

docker compose -f docker/development/docker-compose.yml up -d

Verify the API health before starting the UI:

curl -s http://localhost:8586/healthcheck | jq .

Expected response: {"status":"healthy"}

The UI configuration in openmetadata-ui/src/main/resources/ui/src/constants/constants.ts defines the default API endpoint:

// From openmetadata-ui/src/main/resources/ui/src/constants/constants.ts
export const API_BASE_URL = '';
export const BASE_URL = '/api';
export const SOCKET_BASE_URL = '/api/chat';

During development, the Webpack dev server proxies all /api requests to http://localhost:8585 via the configuration in webpack.config.js.

---

Step 3: Start the Development Server

Launch the hot-reload development environment:

yarn start

This command:

• Starts the Webpack development server on http://localhost:3000
• Opens the default browser automatically
• Enables hot module replacement (HMR) for instant UI updates
• Proxies API calls to the backend at localhost:8585

The terminal displays build progress and any compilation errors. TypeScript strict mode is enabled, so all type errors must be resolved before the build succeeds.

---

Step 4: Verify the UI Development Setup

After yarn start completes, confirm these endpoints:

URL	Expected Result
http://localhost:3000	OpenMetadata login page loads
http://localhost:3000/api/v1/health-check	Proxied to backend; returns health status
http://localhost:8585/api/v1/health-check	Direct backend access (should match above)

Log in with default credentials from conf/openmetadata.yaml:

# From conf/openmetadata.yaml

authentication:
  provider: "basic"
  publicKey: "..."
  # Default admin credentials: admin / admin

---

Key Configuration Files for UI Development

File Path	Purpose
openmetadata-ui/src/main/resources/ui/package.json	Node dependencies and Yarn scripts
openmetadata-ui/src/main/resources/ui/webpack.config.js	Build configuration, dev server, API proxy
openmetadata-ui/src/main/resources/ui/tsconfig.json	TypeScript compiler options
openmetadata-ui/src/main/resources/ui/src/constants/constants.ts	API endpoints, route definitions
openmetadata-ui/src/main/resources/ui/.env	Environment-specific overrides (optional)
conf/openmetadata.yaml	Backend authentication and server settings

---

Customizing the UI Development Environment

Change the Default Port

To run the UI on a different port, modify webpack.config.js:

// From openmetadata-ui/src/main/resources/ui/webpack.config.js
devServer: {
  port: 3001, // Change from default 3000
  proxy: {
    '/api': {
      target: 'http://localhost:8585',
      changeOrigin: true,
    },
  },
},

Connect to a Remote Backend

For testing against a staging API, update the proxy target:

proxy: {
  '/api': {
    target: 'https://staging.openmetadata.org',
    changeOrigin: true,
    secure: false, // For self-signed certificates
  },
},

Enable Debug Logging

Set environment variables before yarn start:

NODE_ENV=development DEBUG=webpack* yarn start

---

Summary

• Install dependencies with yarn install in openmetadata-ui/src/main/resources/ui/
• Start the backend using docker compose -f docker/development/docker-compose.yml up -d
• Launch the UI with yarn start to enable hot-reload development at http://localhost:3000
• Verify connectivity between UI proxy and backend API at http://localhost:8585
• Customize port, backend target, and debug settings via webpack.config.js and environment variables

---

Frequently Asked Questions

What Node.js version is required for OpenMetadata UI development?

OpenMetadata requires Node.js 18.x for UI development. The package.json specifies engine requirements, and using newer versions (19+) may cause dependency conflicts with native modules. Verify your version with node --version before running yarn install.

How do I fix CORS errors when connecting the UI to a remote backend?

CORS errors occur when the backend doesn't recognize the UI's origin. For development, configure the webpack.config.js proxy to route all /api requests through the dev server, which avoids CORS by making requests appear same-origin. For production deployments, update conf/openmetadata.yaml to add allowed origins under corsConfiguration.

Can I run the UI without Docker for the backend?

No, the UI requires a running OpenMetadata backend API at minimum. However, you can use the pre-built Docker images without compiling Java code locally. Run docker compose -f docker/development/docker-compose.yml up -d to start only the backend services, then connect your locally-built UI via the proxy configuration.

Where are UI environment variables defined in OpenMetadata?

UI environment variables are loaded from openmetadata-ui/src/main/resources/ui/.env (optional) and injected at build time through webpack.config.js. Runtime configuration is limited since the UI is a static React application; API endpoints are determined by the webpack dev server proxy setting, not environment variables in the running browser.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}