Tested an OpenMetadata PR Locally Using GitHub Codespaces

A practical guide to running the OpenMetadata backend and UI in a 16 GB Codespace

• Contributing to a large open-source project is not only about writing code. You also need to be able to reproduce the change, run the application locally, verify the behavior, and provide maintainers with evidence that the implementation works.

In this guide, I walk through the workflow I used to test an OpenMetadata pull request inside GitHub Codespaces. The setup used a 16 GB machine and Docker for the backend dependencies, while the OpenMetadata UI was run separately in development mode.

Why GitHub Codespaces?
OpenMetadata has a relatively large development environment involving a Java backend, a React/TypeScript frontend, a database, Elasticsearch, and supporting services. Running everything on a lightweight local machine can be restrictive, especially during builds.

GitHub Codespaces provided a convenient Linux development environment with enough memory to run the required containers and development tooling without changing the project itself.

1. Development Environment
The testing environment included:
GitHub Codespaces with 16 GB RAM

• Java 21
• Maven 3.9.x
• Node.js 22+
• Yarn 1.x
• Docker
• Docker Compose

OpenMetadata source repository
Before starting, I verified the installed tooling:

java -version
mvn -version
node -v
yarn -v
docker --version
docker compose version

2. Starting the OpenMetadata Backend
The OpenMetadata development Docker Compose configuration provides the services required for local testing. From the repository root, I started MySQL, Elasticsearch, database migrations, and the OpenMetadata server:

docker compose -f docker/development/docker-compose.yml up -d \
 mysql \
 elasticsearch \
 execute-migrate-all \
 openmetadata-server

After starting the services, I checked their status with:

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

For backend troubleshooting, the server logs are particularly useful:

docker compose -f docker/development/docker-compose.yml logs -f openmetadata-server

3. Checking the Backend Port
The OpenMetadata API normally listens on port 8585 in this development setup. I used the following command to verify that something was listening on that port:

ss -ltnp | grep 8585

4. Rebuilding After Backend Code Changes
One important detail when working with the Dockerized backend is that changing Java source code does not necessarily mean an existing server container is using that code.
When backend Java files were changed or reverted, I rebuilt the OpenMetadata server image:
docker compose -f docker/development/docker-compose.yml build openmetadata-server
Then I started the services again:

docker compose -f docker/development/docker-compose.yml up -d \
 mysql \
 elasticsearch \
 execute-migrate-all \
 openmetadata-server

This distinction is important: a simple container restart is useful for restarting a service, but rebuilding is necessary when the Docker image needs to contain newly compiled backend code.

5. Running the OpenMetadata UI
I ran the UI separately so that frontend changes could be tested quickly with the Vite development server.

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

The UI development server then serves the frontend and proxies API requests to the OpenMetadata backend. This means the backend needs to be available while testing features that depend on API responses.

6. Getting the Local Administrator Configuration
For local development, the administrator configuration can be inspected in the repository’s development configuration. Rather than publishing credentials in an article, I recommend documenting only how the configuration was located.

grep -Rni "admin.*password\|password.*admin\|admin.*admin" docker/development conf openmetadata-service --exclude-dir=target --exclude-dir=node_modules | head -50

This helps identify development authentication settings and the configured administrator principal. Production credentials, API keys, tokens, OAuth secrets, and other sensitive values should never be included in a public technical article.

Get Jaya Dubey’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

7. Verifying API Connectivity
When the UI appears to load but API-backed functionality does not work, checking the backend directly helps separate frontend issues from backend connectivity problems.

curl http://localhost:8585/api/v1/system/config/auth
curl http://localhost:8585/api/v1/system/config

8. A Repeatable PR Testing Workflow
Create or open a GitHub Codespace with sufficient memory; the tested setup used 16 GB RAM.
Verify Java, Maven, Node.js, Yarn, Docker, and Docker Compose versions.
Start MySQL, Elasticsearch, migrations, and the OpenMetadata server using the development Docker Compose file.
Check container status and backend logs.
Run the OpenMetadata UI with yarn start.
Log in using the administrator configuration from the local development environment.
Exercise the feature introduced by the PR.
Inspect browser/network errors and backend logs if something fails.
Rebuild the backend image whenever Java backend source changes need to be included in the container.
Retest after reverting or modifying configuration changes to verify that the feature does not depend on unnecessary configuration.

9. Troubleshooting Commands I Found Useful
Check running containers:

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

Follow backend logs:

docker compose -f docker/development/docker-compose.yml logs -f openmetadata-server
Check port 8585: 

ss -ltnp | grep 8585

Rebuild backend:

docker compose -f docker/development/docker-compose.yml build openmetadata-server

Restart backend:

• docker compose -f docker/development/docker-compose.yml restart openmetadata-server

Stop development stack:

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

Overcoming the 8 GB Memory Cap in GitHub CodespacesWhen running a massive end-to-end stack like OpenMetadata (which orchestrates a backend server, UI, database, ingestion pipelines, and search components), you need a powerful machine. However, even if you explicitly spin up a 16 GB RAM (4-core) Codespaces machine, you might notice that running resource-intensive tasks triggers Out Of Memory (OOM) failures.

If you verify your resources inside the terminal:

free -h
docker info --format 'Docker memory: {{.MemTotal}} bytes'

You will notice a baffling limitation: your total system memory flags around 7.8Gi and your Docker daemon ceiling hits exactly 8328077312 bytes (~8 GB).

Why does this happen?

• By default, GitHub Codespaces dynamically throttles the internal container environment allocations to 8 GB. This baseline prevents heavy background services from starving the host orchestration layer and VS Code server instances.
• The Solution: Scaling up using hostRequirementsYou can force Codespaces to scale up your environment by specifying hardware requests inside your project’s main dev container configuration file.

1. Update the Dev Container ConfigurationOpen your project’s main dev container file at .devcontainer/devcontainer.json and declare a higher memory constraint inside the outer JSON schema:

{
 "image": "://microsoft.com",
 "features": {
 "ghcr.io/devcontainer-config/features/dot-config:4": {}
 },
 "hostRequirements": {
 "memory": "14g"
 }
}

Note: Set the constraint to 14g instead of the full 16 GB to leave a stable 2 GB buffer for background workspace processes).

2. Rebuild the Environment

For changes to take effect, trigger a clean environment generation:

• Open the VS Code Command Palette using Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac).
• Execute: Dev Containers: Rebuild Container.
• The Result: Because GitHub manages computing nodes dynamically, declaring a robust minimum memory threshold signals their infrastructure to provision a much larger background host.

Once your environment completes rebuilding, checking free -h will likely show your environment upgraded seamlessly to 32 GB of total available system RAM, completely removing the bottleneck for testing complex local PR environments!

10. What This Workflow Taught Me
A successful build is not enough; the actual running service needs to contain the code being tested.
Docker Compose makes it easier to reproduce the backend dependencies required by OpenMetadata.
Running the UI separately provides a faster feedback loop for frontend changes.
Backend logs and browser network requests are complementary debugging tools.
When a configuration change is removed, rebuilding and retesting helps verify whether the application actually depends on it.
Development credentials should be treated carefully even when they are intended only for local testing.

Conclusion

Testing a large open-source project locally can initially look complicated because several services and development tools need to work together. Using a 16 GB GitHub Codespace, Docker Compose for the backend dependencies, and a separate Vite development server for the UI provided a practical workflow for validating an OpenMetadata PR.
The most important lesson is to understand what is actually running: source code, compiled backend artifacts, Docker images, configuration, and the frontend development server all have to line up for a meaningful test.

OpenMetadata • GitHub Codespaces • Docker • Java • React/TypeScript