# How to Run OpenMetadata with Docker Compose for Development

> Easily set up OpenMetadata for development using Docker Compose. This guide shows you how to run MySQL, Elasticsearch, Java backend, and Airflow ingestion locally.

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

---

**You can run OpenMetadata locally using the development Docker Compose stack at [`docker/development/docker-compose.yml`](https://github.com/open-metadata/OpenMetadata/blob/main/docker/development/docker-compose.yml), which provides MySQL, Elasticsearch, the Java backend server, and Airflow-based ingestion services.**

OpenMetadata is a unified metadata platform for the modern data stack. For developers contributing to the project or building integrations, running OpenMetadata with Docker Compose provides a complete, reproducible development environment. This guide walks through the exact steps to launch the full stack using the official development compose file.

## Prerequisites for Running OpenMetadata with Docker Compose

Before starting, ensure you have the following installed:

- **Docker Engine** >= 20.10
- **Docker Compose** v2 plugin

Verify your installation:

```bash
docker --version
docker compose version

```

## Understanding the Development Docker Compose Stack

The development environment is defined in **[`docker/development/docker-compose.yml`](https://github.com/open-metadata/OpenMetadata/blob/main/docker/development/docker-compose.yml)** in the OpenMetadata repository. This compose file orchestrates multiple services that work together to provide a complete metadata platform.

When you run OpenMetadata with Docker Compose, the following services start:

| Service | Purpose | Image Source | Key Ports |
|---------|---------|------------|-----------|
| **mysql** | Relational database for metadata persistence | `docker/mysql/Dockerfile_mysql` | 3306 |
| **elasticsearch** | Search and indexing engine | Official Elasticsearch 9.3.0 | 9200, 9300 |
| **openmetadata-server** | Java backend API (Dropwizard framework) | `docker/development/Dockerfile` | 8585 (API), 8586 (admin), 5005 (debug) |
| **ingestion** | Airflow-based metadata ingestion pipelines | `ingestion/Dockerfile.ci` | 8080 |
| **execute-migrate-all** | One-shot migration runner | Uses [`bootstrap/openmetadata-ops.sh`](https://github.com/open-metadata/OpenMetadata/blob/main/bootstrap/openmetadata-ops.sh) | — |

The compose file also creates a dedicated Docker network called **`ometa_network`** and named volumes like `es-data` and `ingestion-volume-dag-airflow` to persist data across container restarts.

## Step-by-Step: Run OpenMetadata with Docker Compose

### 1. Clone the OpenMetadata Repository

```bash
git clone https://github.com/open-metadata/OpenMetadata.git
cd OpenMetadata

```

### 2. Start the Full Development Stack

Run OpenMetadata with Docker Compose using the development configuration:

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

```

The `-d` flag runs containers in detached mode (background). On first run, Docker builds the custom images for MySQL, the OpenMetadata server, and the ingestion service.

### 3. Verify All Services Are Running

Check the status of all containers:

```bash
docker compose -f docker/development/docker-compose.yml ps

```

You should see all services with status `running` or `healthy`. The `openmetadata-server` container includes a health check that polls `http://localhost:8586/healthcheck`.

Test the health endpoint directly:

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

```

### 4. Access the OpenMetadata UI

Once the server reports healthy, open your browser to:

```

http://localhost:8585

```

Log in with the default admin credentials:
- **Username:** `admin`
- **Password:** `admin`

## Running Selective Services with Docker Compose

You don't need to run the entire stack for all development tasks. Run OpenMetadata with Docker Compose for specific services only:

### Core Services Only (Skip Ingestion)

```bash
docker compose -f docker/development/docker-compose.yml up -d mysql elasticsearch openmetadata-server

```

### Database and Search Only

```bash
docker compose -f docker/development/docker-compose.yml up -d mysql elasticsearch

```

## Optional: Enable SSO Testing with Mock OIDC Provider

The development compose file includes an optional **`mock-oidc-provider`** service for testing authentication flows. To run OpenMetadata with Docker Compose including SSO simulation:

```bash
docker compose -f docker/development/docker-compose.yml --profile sso-test up -d

```

This launches the mock OIDC provider on port 9090, configured in `docker/development/mock-oidc-provider/Dockerfile`.

## Customizing the Development Environment

The compose file exposes extensive environment variables for customization. Common adjustments include:

| Variable | Service | Purpose |
|----------|---------|---------|
| `SERVER_PORT` | openmetadata-server | Change the API port from default 8585 |
| `DB_USER`, `DB_PASSWORD` | mysql | Custom database credentials |
| `ELASTICSEARCH_PORT` | elasticsearch | Change search port from default 9200 |

Override variables using either an `.env` file or inline:

```bash
SERVER_PORT=8586 docker compose -f docker/development/docker-compose.yml up -d

```

## Stopping and Cleaning Up

Stop all services while preserving data volumes:

```bash
docker compose -f docker/development/docker-compose.yml down

```

Stop and completely remove all containers, networks, and **named volumes** (irreversible):

```bash
docker compose -f docker/development/docker-compose.yml down -v

```

Use `-v` when you need a completely fresh environment or when troubleshooting persistent data issues.

## Key Source Files Reference

| File | Purpose |
|------|---------|
| [`docker/development/docker-compose.yml`](https://github.com/open-metadata/OpenMetadata/blob/main/docker/development/docker-compose.yml) | Main development orchestration file |
| `docker/development/Dockerfile` | Java server image build |
| `docker/mysql/Dockerfile_mysql` | MySQL with initialization scripts |
| `ingestion/Dockerfile.ci` | Airflow ingestion image |
| [`bootstrap/openmetadata-ops.sh`](https://github.com/open-metadata/OpenMetadata/blob/main/bootstrap/openmetadata-ops.sh) | Database migration runner |
| `docker/development/mock-oidc-provider/Dockerfile` | Optional SSO test provider |

## Summary

- Run OpenMetadata with Docker Compose using `docker compose -f docker/development/docker-compose.yml up -d` from the repository root
- The development stack includes MySQL, Elasticsearch, the Java backend server, and Airflow-based ingestion services
- Access the UI at `http://localhost:8585` with default credentials `admin/admin`
- Use `--profile sso-test` to include the mock OIDC provider for authentication testing
- Customize behavior through environment variables defined in the compose file
- Clean up completely with `docker compose -f docker/development/docker-compose.yml down -v`

## Frequently Asked Questions

### How long does it take to start OpenMetadata with Docker Compose?

Initial startup takes 5–10 minutes on first run because Docker must build the custom images for the OpenMetadata server, MySQL, and ingestion services. Subsequent starts using cached images complete in 1–2 minutes. The `openmetadata-server` health check passes once the Dropwizard application finishes initializing its database connections and search index.

### Can I run OpenMetadata with Docker Compose on Apple Silicon Macs?

Yes, the development compose file builds images from source rather than using pre-built multi-arch images, so it works on both `amd64` and `arm64` architectures. The official Elasticsearch 9.3.0 image supports Apple Silicon natively. Building the Java server locally on ARM may take longer due to emulation or native compilation, but the process completes successfully.

### What is the difference between development and production Docker Compose files?

The development compose file at [`docker/development/docker-compose.yml`](https://github.com/open-metadata/OpenMetadata/blob/main/docker/development/docker-compose.yml) builds images from local source code and includes debugging ports (5005 for Java remote debug), volume mounts for live code reloading, and health checks with verbose output. Production deployments use pre-built images from Docker Hub or a private registry, disable debug ports, run with read-only filesystems where possible, and use external databases and search clusters rather than containerized ones.