For developers and platform engineers using Backstage, the ability to test configurations, plugins, and templates in an isolated environment is invaluable. That’s where RHDH Local comes in—a lightweight, self-contained way to run Red Hat Developer Hub (RHDH) on your local machine using containers and without a full Kubernetes setup.
Whether you need to validate the configuration of software catalogs, write and test TechDocs, or build RHDH dynamic plugins, RHDH Local simplifies the process, allowing you to iterate quickly and troubleshoot locally before deploying changes to a production system.
Let’s dive into what makes RHDH Local a valuable development tool for platform engineers and how they can get started.
Why Use RHDH Local?
- Test Without Kubernetes
Running a full Backstage-based developer portal typically requires Kubernetes, but not everyone wants to spin up a cluster just to experiment. RHDH Local removes that barrier—just install Docker or Podman, and you’re good to go.
- Experiment with Configurations & Plugins
Need to tweak a homepage layout, test a new dynamic plugin, or configure GitHub integrations? RHDH Local provides a safe playground to validate these changes before rolling them out to a larger team.
- Simple, Fast, and Disposable
Because it runs in a containerized environment, you can spin up RHDH Local in seconds and tear it down just as easily when you're done—without cluttering your system.
- Debugging in a Controlled Setup
For developers working on custom Backstage plugins, RHDH Local offers a structured way to attach a debugger and troubleshoot issues without interfering with a production environment.
- Iterate Quickly On Your Dev Portal Content
When writing and testing TechDocs, Templates, or Catalog items, RHDH Local offers a fast and simple solution that lets you work quickly and retain full control over your setup and your database.
What You Need to Get Started
- x86_64 (amd64) PC (ARM support is coming soon)
- Podman or Docker installed
- Internet connection (to access the code and container images)
- git (for cloning the RHDH Local code repository)
Setting Up RHDH Local
Clone the repository
git clone https://github.com/redhat-developer/rhdh-local.git
cd rhdh-local
Prepare your environment
cp env.sample .env
Most default settings in the copied .env file should work without requiring you to modify them.
The RHDH_IMAGE used by default in the .env file requires an AMD64 based CPU to function. However, the community nightly image (quay.io/rhdh-community/rhdh:next) supports ARM64 and can be used as an alternative on Apple M* based systems.
Start RHDH Local Using Podman
podman-compose up -d
Start RHDH Local Using Docker
docker compose up -d
That's it! If you use the defaults you can now access RHDH Local from your browser at http://localhost:7007 and start your testing.
Modifying Your Configuration
Updating app-config.local.yaml
To apply any configuration changes you make, restart the RHDH container:
podman-compose stop rhdh && podman-compose start rhdh
Or for Docker:
docker compose restart rhdh
Testing Local Dynamic Plugins
To load a new dynamic plugin from a local directory:
- Place the dynamic plugin in the local-plugins/ directory.
To create a dynamic plugin out of the regular Backstage plugin, run npx @janus-idp/cli package export-dynamic-plugin inside the plugin’s source code. The dynamic plugin package will be generated in the dist-dynamic directory.
- Update configs/dynamic-plugins.yaml
Enable the plugin and add any additional configuration that you need.
Then you must run:
podman-compose run install-dynamic-plugins
podman-compose stop rhdh && podman-compose start rhdh
Or for Docker:
docker compose run install-dynamic-plugins
docker compose restart rhdh
Final Thoughts
RHDH Local is a powerful tool for developers and platform engineers looking to test and refine their Backstage-based developer portals in a fast, lightweight, and disposable environment. While it’s not a replacement for a full RHDH deployment, it’s an invaluable resource for local development and testing.
RHDH-Local is a Developer Preview. 🚀 Try it today and let us know what you think. Contributions and feedback are always welcome!
