How to Run OpenMetadata with Docker Compose for Development

You can run OpenMetadata locally using the development Docker Compose stack at 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:

docker --version
docker compose version

Understanding the Development Docker Compose Stack

The development environment is defined in 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	—

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

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:

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:

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:

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)

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

Database and Search Only

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:

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:

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

Stopping and Cleaning Up

Stop all services while preserving data volumes:

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

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

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	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	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 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.

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