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:

   Example command to package an exported third-party plugin

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

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

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

   Example command to push an image to a registry using podman

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

   Example command to push an image to a registry using docker

   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:

   Example 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:

   Example command to obtain the integrity hash of a tgz archive

   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:

   Example dynamic-plugin-config.yaml file

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

4. Run the following command to package the plugins:

   Example command to package a dynamic plugin

   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:

   Example configuration to use packaged plugins in RHDH

   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:

   Example command to publish a plugin package to an NPM registry

   npm publish --registry <npm_registry_url>

   Tip

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

   Example package.json file

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

   If you modify publishConfig after exporting the dynamic plugin, re-run the plugin export command to ensure the correct configuration is included.

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 in the following format in dynamic-plugins.yaml file:

   oci://<image_name>:<tag>!<plugin_name>

   Example configuration in dynamic-plugins.yaml file

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

3. 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

4. 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:

   Example configuration in dynamic-plugins.yaml file

   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:

   Example configuration in dynamic-plugins.yaml file

   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:

   Example code for .npmrc file

   registry=<registry-link>
   //<registry-link>:_authToken=<auth-token>

4. When using OpenShift Container Platform or Kubernetes:

   • 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 1
     type: Opaque
     stringData:
       .npmrc: |
         registry=<registry-link>
         //<registry-link>:_authToken=<auth-token>

     1 1

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

   • 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. Obtain the third-party plugin source code: Clone the plugins repository and navigate to the Todo plugin directory:

   Obtain the third-party plugin source code

   $ git clone https://github.com/backstage/community-plugins
   $ cd community-plugins/workspaces/todo
   $ yarn install

2. Export backend and front-end plugins: Run the following commands to build the backend plugin, adjust package dependencies for dynamic loading, and generate self-contained configuration schema:

   Export the backend plugin

   $ cd todo-backend
   $ npx @red-hat-developer-hub/cli@latest plugin export

   Output of exporting the backend plugin commands

   Building main package
     executing     yarn build ✔
   Packing main package to dist-dynamic/package.json
   Customizing main package in dist-dynamic/package.json for dynamic loading
     moving @backstage/backend-common to peerDependencies
     moving @backstage/backend-openapi-utils to peerDependencies
     moving @backstage/backend-plugin-api to peerDependencies
     moving @backstage/catalog-client to peerDependencies
     moving @backstage/catalog-model to peerDependencies
     moving @backstage/config to peerDependencies
     moving @backstage/errors to peerDependencies
     moving @backstage/integration to peerDependencies
     moving @backstage/plugin-catalog-node to peerDependencies
   Installing private dependencies of the main package
      executing     yarn install --no-immutable ✔
   Validating private dependencies
   Validating plugin entry points
   Saving self-contained config schema in /Users/user/Code/community-plugins/workspaces/todo/plugins/todo-backend/dist-dynamic/dist/configSchema.json

   You can run the following commands to set default dynamic UI configurations, create front-end plugin assets, and to generate a configuration schema for a front-end plugin:

   Export the front-end plugin

   $ cd ../todo
   $ npx @red-hat-developer-hub/cli@latest plugin export

   Output of exporting the front-end plugin commands

   No scalprum config. Using default dynamic UI configuration:
   {
     "name": "backstage-community.plugin-todo",
     "exposedModules": {
       "PluginRoot": "./src/index.ts"
     }
   }
   If you wish to change the defaults, add "scalprum" configuration to plugin "package.json" file, or use the '--scalprum-config' option to specify an external config.
   Packing main package to dist-dynamic/package.json
   Customizing main package in dist-dynamic/package.json for dynamic loading
   Generating dynamic frontend plugin assets in /Users/user/Code/community-plugins/workspaces/todo/plugins/todo/dist-dynamic/dist-scalprum
     263.46 kB  dist-scalprum/static/1417.d5271413.chunk.js
   ...
   ...
   ...
     250 B      dist-scalprum/static/react-syntax-highlighter_languages_highlight_plaintext.0b7d6592.chunk.js
   Saving self-contained config schema in /Users/user/Code/community-plugins/workspaces/todo/plugins/todo/dist-dynamic/dist-scalprum/configSchema.json

3. Package and publish a third-party plugin: Run the following commands to navigate to the workspace directory and package the dynamic plugin to build the OCI image:

   Build an OCI image

   $ cd ../..
   $ npx @red-hat-developer-hub/cli@latest plugin package --tag quay.io/user/backstage-community-plugin-todo:v0.1.1

   Output of building an OCI image commands

     executing     podman --version ✔
   Using existing 'dist-dynamic' directory at plugins/todo
   Using existing 'dist-dynamic' directory at plugins/todo-backend
   Copying 'plugins/todo/dist-dynamic' to '/var/folders/5c/67drc33d0018j6qgtzqpcsbw0000gn/T/package-dynamic-pluginsmcP4mU/backstage-community-plugin-todo
   No plugin configuration found at undefined create this file as needed if this plugin requires configuration
   Copying 'plugins/todo-backend/dist-dynamic' to '/var/folders/5c/67drc33d0018j6qgtzqpcsbw0000gn/T/package-dynamic-pluginsmcP4mU/backstage-community-plugin-todo-backend-dynamic
   No plugin configuration found at undefined create this file as needed if this plugin requires configuration
   Writing plugin registry metadata to '/var/folders/5c/67drc33d0018j6qgtzqpcsbw0000gn/T/package-dynamic-pluginsmcP4mU/index.json'
   Creating image using podman
     executing     echo "from scratch
   COPY . .
   " | podman build --annotation com.redhat.rhdh.plugins='[{"backstage-community-plugin-todo":{"name":"@backstage-community/plugin-todo","version":"0.2.40","description":"A Backstage plugin that lets you browse TODO comments in your source code","backstage":{"role":"frontend-plugin","pluginId":"todo","pluginPackages":["@backstage-community/plugin-todo","@backstage-community/plugin-todo-backend"]},"homepage":"https://backstage.io","repository":{"type":"git","url":"https://github.com/backstage/community-plugins","directory":"workspaces/todo/plugins/todo"},"license":"Apache-2.0"}},{"backstage-community-plugin-todo-backend-dynamic":{"name":"@backstage-community/plugin-todo-backend","version":"0.3.19","description":"A Backstage backend plugin that lets you browse TODO comments in your source code","backstage":{"role":"backend-plugin","pluginId":"todo","pluginPackages":["@backstage-community/plugin-todo","@backstage-community/plugin-todo-backend"]},"homepage":"https://backstage.io","repository":{"type":"git","url":"https://github.com/backstage/community-plugins","directory":"workspaces/todo/plugins/todo-backend"},"license":"Apache-2.0"}}]' -t 'quay.io/user/backstage-community-plugin-todo:v0.1.1' -f - .
       ✔
   Successfully built image quay.io/user/backstage-community-plugin-todo:v0.1.1 with following plugins:
     backstage-community-plugin-todo
     backstage-community-plugin-todo-backend-dynamic
   
   Here is an example dynamic-plugins.yaml for these plugins:
   
   plugins:
     - package: oci://quay.io/user/backstage-community-plugin-todo:v0.1.1!backstage-community-plugin-todo
       disabled: false
     - package: oci://quay.io/user/backstage-community-plugin-todo:v0.1.1!backstage-community-plugin-todo-backend-dynamic
       disabled: false

   Push the OCI image to a container registry:

   $ podman push quay.io/user/backstage-community-plugin-todo:v0.1.1

   Output of pushing the OCI image command

   Getting image source signatures
   Copying blob sha256:86a372c456ae6a7a305cd464d194aaf03660932efd53691998ab3403f87cacb5
   Copying config sha256:3b7f074856ecfbba95a77fa87cfad341e8a30c7069447de8144aea0edfcb603e
   Writing manifest to image destination

4. Install and configure the third-party plugin: Add the following plugin definitions to your dynamic-plugins.yaml file:

   Plugin definitions in dynamic-plugins.yaml file

   packages:
    - package: oci://quay.io/user/backstage-community-plugin-todo:v0.1.1!backstage-community-plugin-todo
      pluginConfig:
        dynamicPlugins:
          frontend:
            backstage-community.plugin-todo:
              mountPoints:
                - mountPoint: entity.page.todo/cards
                  importName: EntityTodoContent
              entityTabs:
                - path: /todo
                  title: Todo
                  mountPoint: entity.page.todo
    - package: oci://quay.io/user/backstage-community-plugin-todo:v0.1.1!backstage-community-plugin-todo-backend-dynamic
      disabled: false

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-marketplace
       disabled: false
       pluginConfig:
         dynamicPlugins:
           frontend:
             red-hat-developer-hub.backstage-plugin-marketplace:
               appIcons:
                 - name: marketplace
                   importName: MarketplaceIcon
               dynamicRoutes:
                 - path: /extensions/catalog
                   importName: DynamicMarketplacePluginRouter
               mountPoints:
                 - mountPoint: application/provider
                   importName: InstallationContextProvider
                 - mountPoint: internal.plugins/tab
                   importName: DynamicMarketplacePluginContent
                   config:
                     path: marketplace
                     title: Catalog
                     icon: CatalogTabIcon
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic
       disabled: false
       pluginConfig:
         extensions:
           installation:
             enabled: true
             saveToSingleFile:
               file: /opt/app-root/src/dynamic-plugins-root/dynamic-plugins.extensions.yaml

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/v1alpha3
         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-marketplace
       disabled: false
       pluginConfig:
         dynamicPlugins:
           frontend:
             red-hat-developer-hub.backstage-plugin-marketplace:
               appIcons:
                 - name: marketplace
                   importName: MarketplaceIcon
               dynamicRoutes:
                 - path: /extensions/catalog
                   importName: DynamicMarketplacePluginRouter
               mountPoints:
                  - mountPoint: application/provider
                    importName: InstallationContextProvider
                 - mountPoint: internal.plugins/tab
                   importName: DynamicMarketplacePluginContent
                   config:
                     path: marketplace
                     title: Catalog
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic
       disabled: false
       pluginConfig:
         extensions:
           installation:
             enabled: true
             saveToSingleFile:
               file: /opt/app-root/src/configs/dynamic-plugins/dynamic-plugins.override.yaml

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 which 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 on 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. The Enable/Disable slider is updated.