Procedure

1. Download the mirroring script:

   $ curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-1.9/.rhdh/scripts/mirror-plugins.sh

2. Run the mirroring script by using the bash command with the appropriate set of options:

   Example

   bash mirror-plugins.sh \
       --plugin-index oci://quay.io/rhdh/plugin-catalog-index:1.9 \
       --to-registry <my.registry.example.com>

   where:

   --to-registry <my.registry.example.com>

   Enter the URL for the target mirror registry where you want to mirror the catalog index.

Procedure

1. Download the mirroring script:

   $ curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-1.9/.rhdh/scripts/mirror-plugins.sh

2. Export all plugins to a local directory:

   Example

   bash mirror-plugins.sh \
       --plugin-index oci://registry.access.redhat.com/rhdh/plugin-catalog-index:1.9 \
       --to-dir </tmp/rhdh-plugins>

   where:

   --to-dir </tmp/rhdh-plugins>

   Enter the local directory path.

3. Import and push the plugins from the local directory to your internal registry:

   Example

   bash mirror-plugins.sh \
       --from-dir /tmp/rhdh-plugins \
       --to-registry <my.registry.example.com>

   where:

   --from-dir </tmp/rhdh-plugins>

   Enter the local directory path.

   --to-registry <my.registry.example.com>

   Enter the URL for the target mirror registry where you want to mirror the catalog index.

Procedure

1. Download the mirroring script:

   $ curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-1.9/.rhdh/scripts/mirror-plugins.sh

2. To mirror individual plugins by specifying their OCI URLs directly, run the mirroring script by using the bash command with the appropriate set of options:

   Example

   bash mirror-plugins.sh \
       --plugins 'oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-quay:1.8.0--1.22.1!backstage-community-plugin-quay' \
                 'oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-github-actions:1.8.0--0.11.1!backstage-community-plugin-github-actions' \
       --to-registry <my.registry.example.com>

   where:

   --to-registry <my.registry.example.com>

   Enter the URL for the target mirror registry where you want to mirror the catalog index.

   Note

   You must quote plugin URLs that contain an OCI subpath (!) to prevent shell interpretation.

Procedure

1. Create a text file listing the plugins to mirror (one per line), as follows:

   Example plugins.txt file:

   oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-quay:1.8.0--1.22.1!backstage-community-plugin-quay
   oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-github-actions:1.8.0--0.11.1!backstage-community-plugin-github-actions
   oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-azure-devops:1.8.0--0.8.2!backstage-community-plugin-azure-devops

2. Download the mirroring script:

   $ curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-1.9/.rhdh/scripts/mirror-plugins.sh

3. Run the mirroring script by using the bash command with the appropriate set of options:

   Example

   bash mirror-plugins.sh \
       --plugin-list plugins.txt \
       --to-registry <my.registry.example.com>

   where:

   --plugin-list plugins.txt

   A text file listing the plugins to mirror.

   --to-registry <my.registry.example.com>

   Enter the URL for the target mirror registry where you want to mirror the catalog index.

Procedure

1. Download the mirroring script:

   $ curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-1.9/.rhdh/scripts/mirror-plugins.sh

2. To combine many plugin sources, run the mirroring script by using the bash command with the appropriate set of options:

   Example

   bash mirror-plugins.sh \
       --plugin-index oci://registry.access.redhat.com/rhdh/plugin-catalog-index:1.9 \
       --plugin-list custom-plugins.txt \
       --plugins 'oci://registry.internal.example.com/custom/my-plugin:1.0' \
       --to-registry registry.example.com

   where:

   --plugin-list custom-plugins.txt

   A text file listing the plugins to mirror.

   --to-registry <my.registry.example.com>

   Enter the URL for the target mirror registry where you want to mirror the catalog index.

Procedure

1. Navigate to the plugin’s root directory (not the dist-dynamic directory).

2. Run the following command to package the plugin into an OCI image:

   $ npx @red-hat-developer-hub/cli@latest plugin package --tag quay.io/example/image:v0.0.1

   In the earlier command, the --tag argument specifies the image name and tag.

3. Run one of the following commands to push the image to a registry:

   $ podman push quay.io/example/image:v0.0.1

   $ docker push quay.io/example/image:v0.0.1

   The output of the package-dynamic-plugins command provides the plugin’s path for use in the dynamic-plugin-config.yaml file.

Procedure

1. Navigate to the dist-dynamic directory.

2. Run the following command to create a tgz archive:

   $ npm pack

   You can obtain the integrity hash from the output of the npm pack command by using the --json flag as follows:

   $ npm pack --json | head -n 10

3. Host the archive on a web server accessible to your RHDH instance, and reference its URL in the dynamic-plugin-config.yaml file as follows:

   plugins:
     - package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz
       integrity: sha512-<hash>

4. Run the following command to package the plugins:

   $ npm pack --pack-destination ~/test/dynamic-plugins-root/

   Tip

   To create a plugin registry using HTTP server on OpenShift Container Platform, run the following commands:

   Example commands to build and deploy an HTTP server in OpenShift Container Platform

   $ oc project my-rhdh-project
   $ oc new-build httpd --name=plugin-registry --binary
   $ oc start-build plugin-registry --from-dir=dynamic-plugins-root --wait
   $ oc new-app --image-stream=plugin-registry

5. Configure your RHDH to use plugins from the HTTP server by editing the dynamic-plugin-config.yaml file:

   plugins:
     - package: http://plugin-registry:8080/backstage-plugin-myplugin-1.9.6.tgz

Procedure

1. Navigate to the dist-dynamic directory.

2. Run the following command to publish the package to your private NPM registry:

   $ npm publish --registry <npm_registry_url>

   Tip

   You can add the following to your package.json file before running the export command:

   {
     "publishConfig": {
       "registry": "<npm_registry_url>"
     }
   }

   If you change publishConfig after exporting the dynamic plugin, re-run the plugin export command to ensure that the correct configuration is in the package.

Procedure

1. To retrieve plugins from an authenticated registry, complete the following steps:

   1. Log in to the container image registry.

      podman login <registry>

   2. Verify the content of the auth.json file created after the login.

      cat ${XDG_RUNTIME_DIR:-~/.config}/containers/auth.json

   3. Create a secret file using the following example:

      oc create secret generic _<secret_name>_ --from-file=auth.json=${XDG_RUNTIME_DIR:-~/.config}/containers/auth.json 1

      • For an Operator-based deployment, replace <secret_name> with dynamic-plugins-registry-auth.
      • For a Helm-based deployment, replace <secret_name> with <Helm_release_name>_-dynamic-plugins-registry-auth.

2. Define the plugin with the oci:// prefix by using one of the following formats in your dynamic-plugins.yaml file:

   Standard explicit definition

   Use the format oci://<image_name>:<tag>!<plugin_path>, as shown in the following example:

   Example configuration in dynamic-plugins.yaml file:

   plugins:
     - disabled: false
       package: oci://quay.io/example/image:v0.0.1!backstage-plugin-myplugin

   Using image digests

   To perform an integrity check, use the image digest in place of the tag in the dynamic-plugins.yaml file as shown in the following example:

   Example configuration in dynamic-plugins.yaml file:

   plugins:
     - disabled: false
       package: oci://quay.io/example/image@sha256:28036abec4dffc714394e4ee433f16a59493db8017795049c831be41c02eb5dc!backstage-plugin-myplugin

   Using path auto-detection

   If the OCI image has only a single plugin, you can omit the path after the exclamation point. The installation program automatically extracts the path from the image metadata, as shown in the following example:

   Example configuration in dynamic-plugins.yaml file:

   plugins:
     - disabled: false
       package: oci://quay.io/example/image:v1.0.0

   Note

   You must package images with the @red-hat-developer-hub/cli to ensure the system applies the io.backstage.dynamic-packages annotation.

   Using version inheritance

   To inherit a version from a base configuration file, for example, dynamic-plugins.default.yaml, use the {{inherit}} placeholder to inherit the v0.0.2 tag, as shown in the following example:

   Example configuration in dynamic-plugins.default.yaml file:

   plugins:
     - disabled: false
       package: oci://quay.io/example/image:v0.0.2!backstage-plugin-myplugin

   Example configuration in dynamic-plugins.yaml file:

   includes:
     - dynamic-plugins.default.yaml
   plugins:
     - disabled: false
       package: oci://quay.io/example/image:{{inherit}}!backstage-plugin-myplugin

   Note

   An error occurs if you use {{inherit}} in the includes file itself or if no matching plugin key exists in the base configuration.

   Combining version inheritance with path omission

   When using {{inherit}} for version inheritance, you can also use the plugin path auto-detection feature by omitting the plugin path entirely. Use this approach when the base configuration in included files already has an explicit path or uses auto-detection itself.

   For example, if the plugin in the included file uses auto-detection that resolves to oci://quay.io/example/image:v0.0.2!example-path, and you use {{inherit}} without a path, it will inherit both the version v0.0.2 and the plugin path example-path.

   Example configuration in dynamic-plugins.default.yaml file:

   plugins:
     - disabled: false
       package: oci://quay.io/example/image:v0.0.2

   Example configuration in dynamic-plugins.yaml file:

   includes:
     - dynamic-plugins.default.yaml
   plugins:
     - disabled: false
       package: oci://quay.io/example/image:{{inherit}}

   Note

   You must define exactly one plugin from that OCI image in the configuration files. The system returns an error if the configuration files contain many plugins or no matching plugins.

3. To apply the changes, restart the RHDH application.

Procedure

1. Specify the archive URL and its integrity hash in the dynamic-plugins.yaml file using the following example:

   plugins:
     - disabled: false
       package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz
       integrity: sha512-9WlbgEdadJNeQxdn1973r5E4kNFvnT9GjLD627GWgrhCaxjCmxqdNW08cj+Bf47mwAtZMt1Ttyo+ZhDRDj9PoA==

2. To apply the changes, restart the RHDH application.

Procedure

1. Run the following command to obtain the integrity hash from the NPM registry:

   $ npm view --registry <registry_link> <npm_package>@<version> dist.integrity

2. Specify the package name, version, and its integrity hash in the dynamic-plugins.yaml file as follows:

   plugins:
     - disabled: false
       package: @example/backstage-plugin-myplugin@1.0.0
       integrity: sha512-9WlbgEdadJNeQxdn1973r5E4kNFvnT9GjLD627GWgrhCaxjCmxqdNW08cj+Bf47mwAtZMt1Ttyo+ZhDRDj9PoA==

3. If you are using a custom NPM registry, create a .npmrc file with the registry URL and authentication details:

   registry=<registry_link>
   //<registry_link>:_authToken=<auth_token>

4. When using OpenShift Container Platform or Kubernetes:

   1. Use the Helm chart to add the .npmrc file by creating a secret. For example:

      Example secret configuration

      apiVersion: v1
      kind: Secret
      metadata:
        name: <release_name>-dynamic-plugins-npmrc
      type: Opaque
      stringData:
        .npmrc: |
          registry=<registry_link>
          //<registry_link>:_authToken=<auth_token>

      Replace <release_name> with your Helm release name. This name is a unique identifier for each chart installation in the Kubernetes cluster.

   2. For RHDH Helm chart, name the secret using the following format for automatic mounting:

      <release_name>-dynamic-plugins-npmrc

5. To apply the changes, restart the RHDH application.

Procedure

1. Go to Administration at the bottom of the sidebar in the Developer Hub.

   The RBAC tab is displayed, showing all the created roles in the Developer Hub.

2. Click Create to create a role.
3. Enter the user name and description (optional) of role in the given fields and click Next.
4. In Add users and groups, select the user name, and click Next.
5. In Add permission policies, select Extensions from the plugins dropdown.
6. Expand Extensions, select both the Create and Read permissions for the Extensions plugin and click Next.

7. Click Create to create the role.

   

Procedure

1. Create the extensions configuration file and save it as dynamic-plugins.extensions.yaml. For example:

   includes:
     - dynamic-plugins.default.yaml
   
   plugins:
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-extensions
       disabled: false
       pluginConfig:
         dynamicPlugins:
           frontend:
             red-hat-developer-hub.backstage-plugin-marketplace:
               translationResources:
                 - importName: marketplaceTranslations
                   ref: marketplaceTranslationRef
                   module: Alpha
               appIcons:
                 - name: pluginsIcon
                   importName: PluginsIcon
               dynamicRoutes:
                 - path: /extensions
                   importName: DynamicMarketplacePluginRouter
                   menuItem:
                     icon: pluginsIcon
                     text: Extensions
                     textKey: menuItem.extensions
               menuItems:
                 extensions:
                   parent: default.admin
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-extensions-backend-dynamic
       disabled: false
       pluginConfig:
         extensions:
           installation:
             enabled: true
             saveToSingleFile:
               file: /opt/app-root/src/dynamic-plugins-root/dynamic-plugins.extensions.yaml

   where:

   translationResources

   Sets the extension point for localization.

2. Copy the file to your cluster by running the following commands:

   oc get pods -n <your_namespace>
   
   oc cp ./dynamic-plugins.extensions.yaml <your_namespace>/<pod_name>:/opt/app-root/src/dynamic-plugins-root/dynamic-plugins.extensions.yaml

3. Update your RHDH application to use this file:

   1. For operator-based installations:

      1. Update your Backstage CR to update the NODE_ENV environment variable to development, as follows:

         apiVersion: rhdh.redhat.com/v1alpha5
         kind: Backstage
         metadata:
           name: developer-hub
           namespace: rhdh
         spec:
           application:
             dynamicPluginsConfigMapName: dynamic-plugins-rhdh
             extraEnvs:
               envs:
                 - name: NODE_ENV
                   value: "development"
               secrets:
                 - name: secrets-rhdh
             extraFiles:
               mountPath: /opt/app-root/src
             route:
               enabled: true
           database:
             enableLocalDb: true

      2. Update your dynamic-plugins-rhdh config map to include your extensions configuration file, as follows:

         kind: ConfigMap
         apiVersion: v1
         metadata:
           name: dynamic-plugins-rhdh
           namespace: rhdh
         data:
          dynamic-plugins.yaml: |
            includes:
              - dynamic-plugins.default.yaml
              - /dynamic-plugins-root/dynamic-plugins.extensions.yaml
            plugins: []

   2. For Helm chart installations:

      1. Upgrade the Helm release to include your extensions configuration file and update the NODE_ENV environment variable to development:

         global:
           auth:
             backend:
               enabled: true
           clusterRouterBase: apps.<clusterName>.com
           dynamic:
             includes:
               - dynamic-plugins.default.yaml
               - /dynamic-plugins-root/dynamic-plugins.extensions.yaml
         upstream:
           backstage:
             extraEnvVars:
               - name: NODE_ENV
                 value: development

      2. Click Upgrade

Procedure

1. Update your dynamic-plugins.override.yaml file:

   includes:
     - dynamic-plugins.default.yaml
   
   plugins:
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-extensions
       disabled: false
       pluginConfig:
         dynamicPlugins:
           frontend:
             red-hat-developer-hub.backstage-plugin-marketplace:
               translationResources:
                 - importName: marketplaceTranslations
                   ref: marketplaceTranslationRef
                   module: Alpha
               appIcons:
                 - name: pluginsIcon
                   importName: PluginsIcon
               dynamicRoutes:
                 - path: /extensions
                   importName: DynamicMarketplacePluginRouter
                   menuItem:
                     icon: pluginsIcon
                     text: Extensions
                     textKey: menuItem.extensions
               menuItems:
                 extensions:
                   parent: default.admin
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-extensions-backend-dynamic
       disabled: false
       pluginConfig:
         extensions:
           installation:
             enabled: true
             saveToSingleFile:
               file: /opt/app-root/src/configs/dynamic-plugins/dynamic-plugins.override.yaml

   where:

   translationResources

   Sets the extension point for localization.

2. Update your compose.yaml file:

   rhdh:
     container_name: rhdh
     environment:
       NODE_OPTIONS: "--inspect=0.0.0.0:9229"
       NODE_ENV: "development"

Procedure

1. Navigate to Extensions.
2. Select a plugin to install.

3. Click the Install button.

   

   The code editor is displayed that displays the plugin default configuration.

4. Update the plugin configuration, if necessary.

   
5. Click Install

6. To view the plugins that require a restart, click View plugins in the alert message.

   
7. Restart your RHDH application.

Verification

1. After you restart your RHDH application, navigate to Extensions.
2. Select the plugin that you have installed.
3. The Actions button is displayed.

Procedure

1. Navigate to Extensions.
2. Select a plugin to enable or disable.

3. Click the Enable/Disable slider.

   

4. To view the plugins that require a restart, click View plugins in the alert message.

   
5. Restart your RHDH application.

Verification

1. After you restart your RHDH application, navigate to Extensions.
2. Select the plugin that you have installed.
3. Verify that the system updated the Enable/Disable slider.