The fastest and simplest way for platform engineers to test Red Hat Developer Hub (RHDH) features locally.
RHDH Local lets you quickly test software catalogs, TechDocs, plugins, templates, and configurations without needing a cluster. Perfect for individual development and testing on your laptop, desktop, or homelab.
Caution
- RHDH Local is NOT a substitute for Red Hat Developer Hub.
- It is for development and testing only, not for production use.
- It is designed for individual developers try out various RHDH features, not for teams as there is no out-of-the-box RBAC support.
- There is no official, commercial support for RHDH Local. Use RHDH Local at your own risk.
-
Prerequisites: Podman v5.4.1+ (recommended) or Docker v28.1.0+ with Compose support
-
Clone and start:
git clone https://github.com/redhat-developer/rhdh-local.git && cd rhdh-local podman compose up -d # or: docker compose up -d
Developer Hub Intelligent Assistant is included by default without OKP-backed product documentation. To configure an LLM provider, opt in to OKP, or disable Intelligent Assistant, see the Developer Hub Intelligent Assistant Guide.
-
Access: Open http://localhost:7007 and log in as 'Guest'
RHDH Local includes comprehensive technical TechDocs covering everything you need to know about it. Once running, access the documentation directly in the application for detailed guides on:
- Getting Started: Understanding RHDH Local's purpose and capabilities
- Loading Content: Adding catalogs, templates, and TechDocs
- Dynamic Plugins: Installing, configuring, and developing plugins
- GitHub Integration: Setting up authentication and content fetching
- Local Development: Working with plugins and configurations
- Operations: Running, restarting, and troubleshooting
The built-in documentation provides step-by-step technical instructions with examples.
Note: Replace
podmanwithdockerif using Docker.
After modifying the plugins configuration, for example after configuring plugins using the Extensions in the RHDH UI:
# Reinstall plugins and restart RHDH
podman compose run install-dynamic-plugins # or: docker compose run install-dynamic-plugins
podman compose stop rhdh # or: docker compose stop rhdh
podman compose start rhdh # or: docker compose start rhdhFor configuration-only changes:
# Just restart RHDH (if plugins haven't changed)
podman compose stop rhdh # or: docker compose stop rhdh
podman compose start rhdh # or: docker compose start rhdhpodman compose down --volumes # or: docker compose down --volumesIf you would like to change your RHDH-Local setup, or add additional features or plugins, please check out the guides below.
- Plugins Guide - how to include your own plugins
- Container Image Guide - how to switch to a more bleeding edge, or commercially supported version of RHDH
- Simulated Proxy Setup - testing in a simulated proxy environment
- PostgreSQL Guide - using PostgreSQL instead of an in-memory database
- Orchestrator Workflow Guide - using Orchestrator with RHDH to develop workflows.
- Developer Hub Intelligent Assistant Guide - configuring an LLM provider for the built-in Developer Hub Intelligent Assistant.
- Developer Hub Intelligent Assistant Maintainer Guide - maintaining and syncing Lightspeed Core configuration files.
To report issues against this repository, please use JIRA with Component: RHDH Local
To browse the existing issues, you can use this Query.
Contributions are welcome! This repository uses a main/dev branching model:
main(default branch) tracks the latest stable GA release of RHDH. Maintainers manage this branch; do not target PRs tomaindirectly.devtracks the upcoming RHDH release (nexttag). All development PRs should targetdev.release-x.ybranches are used for release stabilization and bug fixes for a specific supported release.
See the built-in Contributing guide for details.
Check out the RHDH 2.1 Release Notes for a complete list of new features and enhancements, breaking changes, and known issues.
If you switch your RHDH_IMAGE to 2.1+, be aware of the following potential breaking changes:
-
Plugin wrappers removed from the RHDH image
All plugin wrappers have been removed from the RHDH container image (RHDHPLAN-934). RHDH GA and TP supported plugins are no longer built into the image and are instead fetched as OCI artifacts from a container registry at runtime. This means
./dynamic-plugins/dist/paths no longer work. Useref://plugin-namefor plugins included in the default plugin catalog index image, oroci://with the full package reference otherwise. -
Use
ref://oroci://syntax for plugin references indynamic-plugins.override.yamlUse
ref://plugin-nameto resolve the plugin package from the catalog index listed underincludes, or useoci://with a full package reference for plugins not in the catalog index.For example, instead of:
- package: ./dynamic-plugins/dist/backstage-community-plugin-tech-radar
Use:
- package: ref://backstage-community-plugin-tech-radar
The
oci://syntax with{{inherit}}is still supported and required when you need to specify a!plugin-pathsuffix. See Plugin references for more details. -
Use
enabledinstead ofdisabledThe legacy per-plugin
disabledkey in the dynamic plugins configuration file remains supported but is deprecated. Useenabledfor new or updated entries. For example, replacedisabled: falsewithenabled: true. -
Enable the guest auth provider in your override file
RHDH 2+ no longer bundles auth provider plugins statically. If you are overriding the plugins configuration and need Guest authentication, add:
- package: ref://backstage-plugin-auth-backend-module-guest-provider enabled: true
-
Developer Lightspeed renamed to Developer Hub Intelligent Assistant
The Lightspeed plugins have been renamed to Developer Hub Intelligent Assistant. This feature remains enabled by default, so no action is required unless you reference Lightspeed plugins in your
dynamic-plugins.override.yaml. If so, update to the new names:- package: ref://red-hat-developer-hub-backstage-plugin-intelligent-assistant - package: ref://red-hat-developer-hub-backstage-plugin-intelligent-assistant-backend
The LLM provider configuration has also changed. See the Developer Hub Intelligent Assistant Guide for the updated setup.
-
Update Orchestrator plugin references
If you use the Orchestrator, update the plugin references in your configuration from
oci://URLs toref://syntax:- package: ref://red-hat-developer-hub-backstage-plugin-orchestrator - package: ref://red-hat-developer-hub-backstage-plugin-orchestrator-backend - package: ref://red-hat-developer-hub-backstage-plugin-scaffolder-backend-module-orchestrator - package: ref://red-hat-developer-hub-backstage-plugin-orchestrator-form-widgets
See the Orchestrator Workflow Guide for the full updated configuration and Plugin references for more details on the
ref://syntax. -
Use the Compose overlay for PostgreSQL
PostgreSQL is no longer configured by editing
compose.yamlorapp-config.yamldirectly. Instead, use the separatecompose-with-db.yamloverlay:podman compose -f compose.yaml -f compose-with-db.yaml up -d
See the PostgreSQL Guide for details on optional overrides and major version upgrades.
For dynamic plugin configuration, also see configs/dynamic-plugins/dynamic-plugins.override.example.yaml for a full example.
More details in the RHDH 1.9 Release Notes.
If you switch your RHDH_IMAGE to 1.9+ (default value in this branch), you may need to:
- Update your
dynamic-plugins.override.yaml
Some plugins are no longer bundled in the RHDH image, but have been moved to OCI references.
See Migration Steps for more information.
Also see configs/dynamic-plugins/dynamic-plugins.override.example.yaml for an example.
- Update any scaffolder modules
Ensure they are built for the Backstage version used in RHDH 1.9. Otherwise the backend may fail to start (e.g. TypeError: Cannot read properties of undefined (reading 'id')). See RHDHBUGS-2497 as a known issue.
Copyright Red Hat
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.