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 @janus-idp/cli@latest package package-dynamic-plugins --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 export-dynamic-plugin command to ensure the correct configuration is included.

Procedure

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

2. Configure authentication for private registries by setting the REGISTRY_AUTH_FILE environment variable to the path of the registry configuration file. For example, ~/.config/containers/auth.json or ~/.docker/config.json.

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

   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-url> <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-url>
   //<registry-url>:_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-url>
         //<registry-url>:_authToken=<auth-token>

     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.

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 @janus-idp/cli@latest package export-dynamic-plugin

   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 @janus-idp/cli@latest package export-dynamic-plugin

   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 @janus-idp/cli@latest package package-dynamic-plugins --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