# How to Configure the OpenMetadata UI for Development

> Configure the OpenMetadata UI for development easily. Learn how to set up your local environment with yarn install and yarn start for seamless UI development and integration.

- Repository: [OpenMetadata/OpenMetadata](https://github.com/open-metadata/OpenMetadata)
- Tags: how-to-guide
- Published: 2026-04-23

---

**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:

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

yarn install

```

This command reads [`package.json`](https://github.com/open-metadata/OpenMetadata/blob/main/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:

```bash

# From repository root

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

```

Verify the API health before starting the UI:

```bash
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`](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-ui/src/main/resources/ui/src/constants/constants.ts) defines the default API endpoint:

```typescript
// 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`](https://github.com/open-metadata/OpenMetadata/blob/main/webpack.config.js).

---

## Step 3: Start the Development Server

Launch the hot-reload development environment:

```bash
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`](https://github.com/open-metadata/OpenMetadata/blob/main/conf/openmetadata.yaml):

```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`](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-ui/src/main/resources/ui/package.json) | Node dependencies and Yarn scripts |
| [`openmetadata-ui/src/main/resources/ui/webpack.config.js`](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-ui/src/main/resources/ui/webpack.config.js) | Build configuration, dev server, API proxy |
| [`openmetadata-ui/src/main/resources/ui/tsconfig.json`](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-ui/src/main/resources/ui/tsconfig.json) | TypeScript compiler options |
| [`openmetadata-ui/src/main/resources/ui/src/constants/constants.ts`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/webpack.config.js):

```javascript
// 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:

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

```

### Enable Debug Logging

Set environment variables before `yarn start`:

```bash
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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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.