
Testing an OpenMetadata Pull Request with GitHub Codespaces
A practical guide to running the OpenMetadata backend and UI in a 16 GB Codespace
A complete contribution also requires being able to reproduce the change, run the application locally, verify the behavior, and determine whether the implementation works as expected.
In this article, I walk through the workflow I used to test an OpenMetadata pull request inside GitHub Codespaces.
The setup used a 16 GB GitHub Codespace, Docker Compose for the backend and supporting services, and the OpenMetadata UI running separately in development mode.
Why GitHub Codespaces?
OpenMetadata has a relatively large development environment involving several technologies:
- Java backend
- React and TypeScript frontend
- MySQL
- Elasticsearch
- Maven
- Node.js and Yarn
- Docker and Docker Compose
- Running the complete development environment on a lightweight local machine can be restrictive, especially when compiling the Java backend and running multiple Docker containers.
- GitHub Codespaces provided a convenient Linux development environment with enough memory to run the required services and development tools without changing the project itself.
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
```
- Verifying the versions first helps identify environment-related problems before starting the application.
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.
```
docker compose -f docker/development/docker-compose.yml ps
```
For backend troubleshooting, the OpenMetadata server logs are particularly useful.
```
docker compose -f docker/development/docker-compose.yml logs -f openmetadata-server
```
The logs can help identify problems such as startup failures, database connectivity issues, migration problems, and configuration errors.
Checking the Backend Port
In this development setup, the OpenMetadata API normally listens on port 8585.
I verified that something was listening on that port with:
```
ss -ltnp | grep 8585
```
This is a simple but useful check when the frontend appears to be running but API requests are failing.
Rebuilding After Backend Code Changes
- One important detail when working with a Dockerized backend is understanding the difference between restarting a container and rebuilding the Docker image.
- Changing a Java source file does not necessarily mean that an existing server container is running the modified 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 required services again.
```
docker compose -f docker/development/docker-compose.yml up -d \
mysql \
elasticsearch \
execute-migrate-all \
openmetadata-server
```
This distinction is important:
- Restarting a container starts the existing container again.
- Rebuilding creates a new image containing the updated application artifacts.
- Starting the services then runs the services using the available images.
For backend Java changes, rebuilding ensures that the Dockerized server contains the version of the code being tested.
- Running the OpenMetadata UI
I ran the OpenMetadata UI separately to get a faster feedback loop for frontend changes.
From the UI directory:
```
cd openmetadata-ui/src/main/resources/ui
yarn start
```
The UI development server runs independently from the Dockerized backend.
This allows frontend changes to be tested quickly without rebuilding the entire backend environment after every UI change.
The backend still needs to be available because the UI makes API requests to the OpenMetadata server
- 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 a public article, it is better to document how the configuration was located.
For example:
```
grep -Rni "admin.*password|password.*admin|admin.*admin" \
docker/development conf openmetadata-service \
--exclude-dir=target \
--exclude-dir=node_modules | head -50
```
This can help identify development authentication settings and the configured administrator principal.
Important: Do not publish production credentials, API keys, access tokens, OAuth secrets, database passwords, or other sensitive values in a public technical article.
Even credentials intended only for local development should be handled carefully.
- Verifying API Connectivity
When the UI appears to load but API-backed functionality does not work, checking the backend directly helps separate frontend problems from backend connectivity problems.
- Use curl
These requests help confirm that the OpenMetadata server is reachable and responding to API requests.
If the backend is unavailable, browser developer tools may show connection errors for requests going to port 8585.
- Testing the Pull Request
Once the backend and UI were running, I could exercise the functionality introduced by the pull request.
The testing cycle was:
1. Start the required backend services.
2. Confirm that the OpenMetadata server is running.
3. Start the UI development server.
4. Open the application in the browser.
5. Log in using the administrator configuration available in the local development environment.
6. Navigate to the functionality affected by the pull request.
7. Exercise the changed behavior.
8. Inspect browser network requests if something does not behave as expected.
9. Check the OpenMetadata server logs for backend-related errors.
10. Rebuild the backend if Java source code changes need to be included.
11. Retest after modifying or reverting configuration changes.
This process makes it easier to determine whether a failure is caused by the frontend, backend, Docker environment, configuration, or the implementation itself.
- A Repeatable PR Testing Workflow
The complete workflow can be summarized as:
GitHub Codespace
↓
Java and Maven
↓
Node.js and Yarn
↓
Docker Compose
- MySQL
- Elasticsearch
- Database migrations
- OpenMetadata Server
↓
OpenMetadata UI
- Vite development server
- Step 1: Create the Codespace
Create or open a GitHub Codespace with sufficient resources.
The environment used for this testing workflow had 16 GB RAM.
- Step 2: Verify Development Tools
```
java -version
mvn -version
node -v
yarn -v
docker --version
docker compose version
```
- Step 3: Start Backend Services
```
docker compose -f docker/development/docker-compose.yml up -d \
mysql \
elasticsearch \
execute-migrate-all \
openmetadata-server
```
- Step 4: Verify Containers
```
docker compose -f docker/development/docker-compose.yml ps
```
- Step 5: Inspect Backend Logs
```
docker compose -f docker/development/docker-compose.yml logs -f openmetadata-server
```
- Step 6: Start the UI
```
cd openmetadata-ui/src/main/resources/ui
yarn start
```
- Step 7: Test the Feature
Log in to the local OpenMetadata instance and exercise the functionality modified by the pull request.
- Step 8: Troubleshoot
Use browser developer tools, API requests, Docker status, and backend logs to isolate problems.
- Step 9: Rebuild When Necessary
If backend Java source code changes need to be included in the running server:
```
docker compose -f docker/development/docker-compose.yml build openmetadata-server
```
Then start the required services again.
Troubleshooting Commands
Check Running Containers
- docker compose -f docker/development/docker-compose.yml ps
Follow OpenMetadata Server Logs
- docker compose -f docker/development/docker-compose.yml logs -f openmetadata-server
Check Port 8585
- ss -ltnp | grep 8585
Rebuild the Backend
- docker compose -f docker/development/docker-compose.yml build openmetadata-server
Restart the Backend
- docker compose -f docker/development/docker-compose.yml restart openmetadata-server
Stop the Development Stack
- docker compose -f docker/development/docker-compose.yml down
What This Workflow Taught Me
1. A successful build does not necessarily mean the running application contains your changes
This was one of the most important lessons from the testing process.
When working with Dockerized services, it is necessary to understand the relationship between:
Source code → Build artifacts → Docker image → Running container
A change to Java source code may require rebuilding the server image before the running application actually contains that change.
2. Docker Compose makes complex backend dependencies easier to reproduce
Instead of manually installing and configuring every dependency, the development Compose configuration provides a reproducible way to start services such as MySQL, Elasticsearch, database migrations, and the OpenMetadata server.
3. Running the UI separately provides a faster feedback loop
Using the Vite development server allows frontend changes to be tested without rebuilding the complete backend environment.
This is particularly useful when working on UI-focused pull requests.
4. Browser and backend debugging complement each other
Browser developer tools help identify:
- Failed API requests
- HTTP status codes
- Proxy errors
- Request and response payloads
Backend logs help identify:
- Server startup failures
- Database problems
- Configuration issues
- API errors
- Runtime exceptions
Using both provides a much clearer picture than relying on either one alone.
5. Configuration changes should be validated, not assumed
If a configuration change is removed or modified, rebuilding and retesting can determine whether the application actually depends on it.
This is particularly useful when reviewing a pull request where configuration changes are part of the implementation.
6. Development credentials still need to be handled carefully
Even when credentials are intended only for local development, publishing them unnecessarily is not a good practice.
A technical article should explain how to locate development configuration rather than exposing passwords, tokens, or other secrets.
Conclusion
Testing a large open-source project locally can initially look complicated because several services, languages, and development tools need to work together.
Using a 16 GB GitHub Codespace, Docker Compose for the OpenMetadata backend and supporting services, and a separate Vite development server for the UI provided a practical workflow for validating an OpenMetadata pull request.
The most important lesson was to understand what is actually running.
For a meaningful test, the following pieces need to line up:
Source code → Compiled artifacts → Docker image → Running backend → Frontend development server → Configuration
Once that relationship is clear, debugging becomes much more systematic.
Instead of simply asking, "Did the build pass?", the more useful question is:
"Is the application currently running the exact code and configuration that I intend to test?"
That mindset is valuable when contributing to any large open-source project, not just OpenMetadata.
Topics
OpenMetadata · GitHub Codespaces · Docker · Docker Compose · Java · Maven · React · TypeScript · Vite · Open Source · Software Development
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article