From 6c5bb45c44e0a29346adef2182731d897d72250f Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Tue, 26 Nov 2024 18:33:02 +0530 Subject: [PATCH 01/10] RHIDP-4807: Third-party plugin installation in RHDH --- .../assembly-installing-rhdh-plugins.adoc | 15 +- ...mbly-third-party-plugins-installation.adoc | 114 +++++++++++++ .../proc-export-third-party-plugins-rhdh.adoc | 35 ++++ ...ll-plugins-using-custom-npm-registry.adoc} | 2 +- ...proc-install-third-party-plugins-rhdh.adoc | 138 +++++++++++++++ ...oc-package-third-party-dynamic-plugin.adoc | 158 ++++++++++++++++++ titles/plugins-rhdh-install/master.adoc | 15 +- 7 files changed, 464 insertions(+), 13 deletions(-) create mode 100644 assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc create mode 100644 modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc rename modules/dynamic-plugins/{proc-using-custom-npm-registry.adoc => proc-install-plugins-using-custom-npm-registry.adoc} (93%) create mode 100644 modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc create mode 100644 modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc diff --git a/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc index 70b58f271b..5b43a141ac 100644 --- a/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc @@ -6,20 +6,17 @@ The dynamic plugin support is based on the backend plugin manager package, which You can use the dynamic plugins that come preinstalled with {product} or install external dynamic plugins from a public NPM registry. // Operator installation -include::../modules/dynamic-plugins/proc-config-dynamic-plugins-rhdh-operator.adoc[leveloffset=+1] +include::../modules/dynamic-plugins/proc-config-dynamic-plugins-rhdh-operator.adoc[leveloffset=+2] // Helm installation -include::../modules/dynamic-plugins/con-install-dynamic-plugin-helm.adoc[leveloffset=+1] -include::../modules/dynamic-plugins/proc-obtaining-integrity-checksum.adoc[leveloffset=+2] -include::../modules/dynamic-plugins/ref-example-dynamic-plugin-helm-installations.adoc[leveloffset=+2] -include::../modules/dynamic-plugins/proc-rhdh-example-external-dynamic-plugins.adoc[leveloffset=+2] +include::../modules/dynamic-plugins/con-install-dynamic-plugin-helm.adoc[leveloffset=+2] +include::../modules/dynamic-plugins/proc-obtaining-integrity-checksum.adoc[leveloffset=+3] +include::../modules/dynamic-plugins/ref-example-dynamic-plugin-helm-installations.adoc[leveloffset=+3] +include::../modules/dynamic-plugins/proc-rhdh-example-external-dynamic-plugins.adoc[leveloffset=+3] // Air gapped environment //include::../modules/dynamic-plugins/proc-rhdh-installing-external-dynamic-plugins-airgapped.adoc[leveloffset=+1] -include::../modules/dynamic-plugins/proc-using-custom-npm-registry.adoc[leveloffset=+1] - -// Viewing installed plugins -include::../modules/dynamic-plugins/proc-viewing-installed-plugins.adoc[leveloffset=+1] +include::../modules/dynamic-plugins/proc-install-plugins-using-custom-npm-registry.adoc[leveloffset=+2] //basic plugin configuration //include::../modules/dynamic-plugins/con-basic-config-dynamic-plugins.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc b/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc new file mode 100644 index 0000000000..2359c4af22 --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc @@ -0,0 +1,114 @@ +[id="assembly-third-party-plugins-installation"] += Third-party plugins in {product} +:context: assembly-third-party-plugins-installation + +In {product}, third-party dynamic plugins can be integrated seamlessly, enabling the use of external plugins alongside native ones. This flexibility allows you to enhance the platform’s functionality without modifying its core structure. To add third-party dynamic plugins, you can either export them as standalone packages or wrap them in custom wrappers, especially if you want to adjust the plugin’s dependencies or configurations for compatibility. + +The third-party plugins are typically packaged as dynamic plugins, which means they can be loaded at runtime, enabling you to easily manage external modules without rebuilding the entire application. The process involves creating a wrapper that exports the plugin code, ensuring that dependencies are correctly bundled or marked as shared, depending on their relationship to the {product-short} environment. + +To integrate a third-party plugin into {product-short}: + +. First, obtain the plugin's source code. +. Export the plugin as a dynamic plugin package. See xref:proc-export-third-party-plugins-rhdh_{context}[]. +. Package and publish the dynamic plugin. See xref:proc-package-third-party-dynamic-plugin_{context}[]. +. Install the plugin in the {product-short} environment. See xref:proc-install-third-party-plugins-rhdh_{context}[]. + +The third-party plugins include: + +Backend plugins:: ++ +-- +To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with, the new backend system. Additionally, these plugins must be rebuilt using a dedicated CLI command. + +The new backend system is created using `createBackendPlugin()` or `createBackendModule()`. You must export the new backend system as the default export from either the main package or an alpha package (if support exists in alpha). The dynamic export mechanism automatically identifies private dependencies, and adds them to the `bundleDependencies` field in the `package.json` file. This mechanism ensures that the dynamic plugin package is self-contained, with private dependencies bundled within a private `node_modules` folder. + +The backend plugins contains two types of dependencies, including: + +* *Shared dependencies* are provided by the Backstage application and listed as `peerDependencies` in `package.json` file, not bundled in the dynamic plugin package. By default, all `@backstage` packages are shared. ++ +You can use the `--shared-package` flag to specify shared dependencies. To treat a `@backstage` package as private, use the negation prefix (`!`). + +* *Embedded dependencies* are bundled into the dynamic plugin package with their dependencies hoisted to the top level. By default, packages with `-node` or `-common` suffixes are embedded. ++ +You can use the `--embed-package` flag to specify additional embedded packages, including those in the same monorepo that do not follow the default naming convention. + +The following is an example of exporting a dynamic plugin with shared and embedded packages: + +.Example dynamic plugin export with shared and embedded packages +[source,bash] +---- +npx @janus-idp/cli@latest export-dynamic-plugin --shared-package '!/@backstage/plugin-notifications/'<1> --embed-package @backstage/plugin-notifications-backend <2> +---- + +<1> `@backstage/plugin-notifications` package is treated as a private dependency and is bundled in the dynamic plugin package, despite being in the `@backstage` scope. +<2> `@backstage/plugin-notifications-backend` package is marked as an embedded dependency and is bundled in the dynamic plugin package. +-- + +Frontend plugins:: ++ +-- +Frontend plugins can leverage Scalprum for configuration, which the CLI can generate automatically during the export process. The generated default configuration is logged when running the following command: + +.Example command to log the default configuration +[source,bash] +---- +npx @janus-idp/cli@latest export-dynamic +---- + +The following is an example of default Scalprum configuration: + +.Default Scalprum configuration +[source,json] +---- +"scalprum": { + "name": "", // The Webpack container name matches the NPM package name, with "@" replaced by "." and "/" removed. + "exposedModules": { + "PluginRoot": "./src/index.ts" // The default module name is "PluginRoot" and doesn't need explicit specification in the app-config.yaml file. + } +} +---- + +To customize Scalprum, add a `scalprum` section to the `package.json` file. For example: + +.Example Scalprum customization +[source,json] +---- +"scalprum": { + "name": "custom-package-name", + "exposedModules": { + "FooModuleName": "./src/foo.ts", + "BarModuleName": "./src/bar.ts" + // Define multiple modules here, with each exposed as a separate entry point in the Webpack container. + } +} +---- + +Dynamic plugins might need adjustments for {product-short} needs, such as static JSX for mountpoints or dynamic routes. These changes are optional but might be incompatible with static plugins. + +To include static JSX, define an additional export and use it as the dynamic plugin's `importName`. For example: + +.Example static and dynamic plugin export +[source,tsx] +---- +// For a static plugin +export const EntityTechdocsContent = () => {...} + +// For a dynamic plugin +export const DynamicEntityTechdocsContent = { + element: EntityTechdocsContent, + staticJSXContent: ( + + + + ), +}; +---- +-- +//Export third-party plugins +include::../modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc[leveloffset=+2] + +//package and publish third-party plugins +include::../modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc[leveloffset=+2] + +//install third-party plugins +include::../modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc[leveloffset=+2] \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc new file mode 100644 index 0000000000..2ec942bf7f --- /dev/null +++ b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc @@ -0,0 +1,35 @@ +[id="proc-export-third-party-plugins-rhdh_{context}"] += Exporting third-party plugins in {product} + +To use dynamic plugins in {product}, the plugins must be exported as separate packages. These packages contain the plugin code and dependencies, ready for dynamic plugin integration into {product-short}. + +.Prerequisites +* The `@janus-idp/cli` package is installed. Use the latest version (`@latest` tag) for compatibility with the most recent features and fixes. +* The third-party plugin must have a valid package.json file in its root directory, containing all required metadata and dependencies. +* Node.js and NPM is installed and configured. +* You have access to a private NPM registry for publishing and distributing the exported plugin package. +* The third-party plugin is compatible with your {product} version. For more information, see link:https://github.com/janus-idp/backstage-showcase/blob/main/docs/dynamic-plugins/versions.md[Version compatibility matrix]. + +.Procedure +. Use the `package export-dynamic-plugin` command from the `@janus-idp/cli` package to export the plugin: ++ +-- +.Example command to export a third-party plugin +[source,bash] +---- +npx @janus-idp/cli@latest package export-dynamic-plugin +---- + +Ensure that you execute the previous command in the root directory of the plugin's JavaScript package (containing `package.json` file). +-- + +. Located the exported package in the `dist-dynamic` sub-folder. +. Use `npm pack` or a private NPM registry to package or distribute the plugin. For more information, see xref:proc-package-third-party-dynamic-plugin_{context}[]. ++ +-- +[IMPORTANT] +==== +Ensure that you do not push derived dynamic plugin packages to a public NPM registry. Use a private NPM registry only. +==== +-- + diff --git a/modules/dynamic-plugins/proc-using-custom-npm-registry.adoc b/modules/dynamic-plugins/proc-install-plugins-using-custom-npm-registry.adoc similarity index 93% rename from modules/dynamic-plugins/proc-using-custom-npm-registry.adoc rename to modules/dynamic-plugins/proc-install-plugins-using-custom-npm-registry.adoc index 16aefcddb4..f09e8dc015 100644 --- a/modules/dynamic-plugins/proc-using-custom-npm-registry.adoc +++ b/modules/dynamic-plugins/proc-install-plugins-using-custom-npm-registry.adoc @@ -1,4 +1,4 @@ -[id="proc-using-custom-npm-registry"] +[id="proc-install-plugins-using-custom-npm-registry"] //= Using a custom NPM registry for dynamic plugin packages = Installing dynamic plugins in an air-gapped environment diff --git a/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc new file mode 100644 index 0000000000..307acabe04 --- /dev/null +++ b/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc @@ -0,0 +1,138 @@ +[id="proc-install-third-party-plugins-rhdh_{context}"] += Installing third-party plugins in {product} + +You can install a third-party plugins in {product} without rebuilding the {product-very-short} application. + +.Prerequisites +* The third-party plugin is packaged as a dynamic plugin in one of the following formats: +** OCI image +** TGZ file +** NPM or JavaScript package + +For more information about packaging a third-party plugin, see xref:proc-package-third-party-dynamic-plugin_{context}[]. + +[NOTE] +==== +You can also load dynamic plugins from a plain directory, though this is intended for development or testing purposes and is not recommended for production, except for plugins included in the {product-very-short} container image. +==== + +.Procedure +Load a plugin packaged as an OCI image:: ++ +-- +. Define the plugin with the `oci://` prefix in the following format in `dynamic-plugins.default.yaml` file: ++ +`oci://:!` ++ +.Example configuration in `dynamic-plugins.default.yaml` file +[source,yaml] +---- +plugins: + - disabled: false + package: oci://quay.io/example/image:v0.0.1!backstage-plugin-myplugin +---- + +. 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`. + +. To perform an integrity check, use the image digest in place of the tag in `dynamic-plugins.default.yaml` file as follows: ++ +.Example configuration in `dynamic-plugins.default.yaml` file +[source,yaml] +---- +plugins: + - disabled: false + package: oci://quay.io/example/image@sha256:! +---- + +. To apply the changes, restart the {product-very-short} application. +-- + +Load a plugin packaged as a TGZ file:: ++ +-- +. Specify the archive URL and its integrity hash in the `dynamic-plugins.default.yaml` file using the following format: ++ +.Configuration format in `dynamic-plugins.default.yaml` file +[source,yaml] +---- +plugins: + - disabled: false + package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz + integrity: +---- ++ +.Example configuration in `dynamic-plugins.default.yaml` file +[source,yaml] +---- +plugins: + - disabled: false + package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz + integrity: sha512-9WlbgEdadJNeQxdn1973r5E4kNFvnT9GjLD627GWgrhCaxjCmxqdNW08cj+Bf47mwAtZMt1Ttyo+ZhDRDj9PoA== +---- + +. To apply the changes, restart the {product-very-short} application. +-- + +Load a plugin packaged as a JavaScript or NPM package:: ++ +-- +. Run the following command to obtain the integrity hash from the NPM registry: ++ +[source,bash] +---- +npm view --registry @backstage-community/plugin-todo-dynamic@ dist.integrity +---- + +. Specify the package name, version, and its integrity hash in the `dynamic-plugins.default.yaml` file as follows: ++ +.Configuration format in `dynamic-plugins.default.yaml` file +[source,yaml] +---- +plugins: + - disabled: false + package: @example/backstage-plugin-myplugin@1.0.0 + integrity: +---- ++ +.Example configuration in `dynamic-plugins.default.yaml` file +[source,yaml] +---- +plugins: + - disabled: false + package: @example/backstage-plugin-myplugin@1.0.0 + integrity: sha512-9WlbgEdadJNeQxdn1973r5E4kNFvnT9GjLD627GWgrhCaxjCmxqdNW08cj+Bf47mwAtZMt1Ttyo+ZhDRDj9PoA== +---- + +. If you are using a custom NPM registry, create a `.npmrc` file with the registry URL and authentication details: ++ +.Example code for `.npmrc` file +[source,text] +---- +registry= +//:_authToken= +---- + +. When using {ocp-short} or Kubernetes: ++ +* Create a secret with the `.npmrc` content as follows: ++ +.Example secret configuration +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + name: dynamic-plugins-npmrc +type: Opaque +stringData: + .npmrc: | + registry= + //:_authToken= +---- + +* For {product-very-short} Helm chart, name the secret using the following format for automatic mounting: ++ +`-dynamic-plugins-npmrc` + +. To apply the changes, restart the {product-very-short} application. +-- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc b/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc new file mode 100644 index 0000000000..4ce75d728c --- /dev/null +++ b/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc @@ -0,0 +1,158 @@ +[id="proc-package-third-party-dynamic-plugin_{context}"] += Packaging and publishing third-party plugins as dynamic plugins + +To package a third-party plugin as a dynamic plugin, you need to access to its source code and must export a plugin using the `@janus-idp/cli`. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. + +After exporting a third-party plugin, you can convert the package into one of the following supported formats: + +* Open Container Initiative (OCI) image (recommended) +* TGZ file +* JavaScript package + +[IMPORTANT] +==== +Exported dynamic plugin packages must only be published to private NPM registries. +==== + +[#convert-to-oci-image] +== Converting a dynamic plugin package to an OCI image + +.Prerequisites +* You have installed `podman` or `docker`. +* You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. + +.Procedure +. Navigate to the exported plugin's root directory (not the `dist-dynamic` directory). +. Run the following command to package the plugin into an OCI image: ++ +-- +.Example command to package an exported third-party plugin +[source,bash] +---- +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. +-- +. Run one of the following commands to push the image to a registry: ++ +-- +.Example command to push an image to a registry using podman +[source,bash] +---- +podman push quay.io/example/image:v0.0.1 +---- + +.Example command to push an image to a registry using docker +[source,bash] +---- +docker push quay.io/example/image:v0.0.1 +---- + +The output of the previous commands provides the plugin's path for use in the `dynamic-plugin-config.yaml` file. +-- + +[#convert-to-tgz] +== Converting a dynamic plugin package to a TGZ file + +.Prerequisites +* You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. + +.Procedure +. Navigate to the `dist-dynamic` directory. +. Run the following command to create a `tgz` archive: ++ +-- +.Example command to create a `tgz` archive +[source,bash] +---- +npm pack +---- +-- +. To retrieve the integrity hash of the archive, run the following command: ++ +-- +.Example command to retrieve the integrity hash of a `tgz` archive +[source,bash] +---- +npm pack --json | jq -r '.[0].integrity' +---- +-- +. Host the archive on a web server accessible to your {product-very-short} instance, and reference its URL in the `dynamic-plugin-config.yaml` file as follows: ++ +-- +.Example `dynamic-plugin-config.yaml` file +[source,yaml] +---- +plugins: + - package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz + integrity: sha512- +---- +-- +. Run the following command to package the plugins: ++ +-- +.Example command to package a dynamic plugin +[source,bash] +---- +npm pack --pack-destination ~/test/dynamic-plugins-root/ +---- +-- +. Build and deploy an HTTP server in {ocp-short}: ++ +-- +.Example commands to build and deploy an HTTP server in {ocp-short} +[source,bash] +---- +oc project rhdh +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 +---- +-- +. Configure your {product-very-short} to use plugins from the HTTP server by editing the `dynamic-plugin-config.yaml` file: ++ +-- +.Example configuration to use packaged plugins in {product-very-short} +[source,yaml] +---- +plugins: + - package: http://plugin-registry:8080/backstage-plugin-myplugin-1.9.6.tgz +---- +-- + +[#convert-to-jsp] +== Converting a dynamic plugin to a JavaScript package + +.Prerequisites +* You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. + +.Procedure +. Navigate to the `dist-dynamic` directory. +. Run the following command to publish the package to your private NPM registry: ++ +-- +.Example command to publish a plugin package to an NPM registry +[source,bash] +---- +npm publish --registry +---- + +[TIP] +==== +You can add the following to your `package.json` file before running the `export` command: + +.Example `package.json` file +[source,json] +---- +{ + "publishConfig": { + "registry": "" + } +} +---- + +If you modify the `publishConfig` after exporting the dynamic plugin, re-run the `export-dynamic-plugin` command to ensure the correct configuration is included. +==== +-- + diff --git a/titles/plugins-rhdh-install/master.adoc b/titles/plugins-rhdh-install/master.adoc index c074fc579f..9b2ba0ca02 100644 --- a/titles/plugins-rhdh-install/master.adoc +++ b/titles/plugins-rhdh-install/master.adoc @@ -2,8 +2,17 @@ include::artifacts/attributes.adoc[] :context: title-plugins-rhdh-about :imagesdir: images -:title: Installing and viewing dynamic plugins -:subtitle: Installing dynamic plugins +:title: Installing and viewing plugins in {product} +:subtitle: Installing plugins in {product} :abstract: Administrative users can install and configure plugins to enable other users to use plugins to extend {product-very-short} functionality. -include::assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc[] += {title} + +//installing dynamic plugins +include::assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc[leveloffset=+1] + +//third-party plugins +include::assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc[leveloffset=+1] + +// Viewing installed plugins +include::modules/dynamic-plugins/proc-viewing-installed-plugins.adoc[leveloffset=+1] From 439088018dc1dfec87bd4f6fc0e746790fdd1340 Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Tue, 26 Nov 2024 19:28:46 +0530 Subject: [PATCH 02/10] fixed minor issues --- ...embly-third-party-plugins-installation.adoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc b/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc index 2359c4af22..eac1d88bc0 100644 --- a/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc +++ b/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc @@ -2,7 +2,7 @@ = Third-party plugins in {product} :context: assembly-third-party-plugins-installation -In {product}, third-party dynamic plugins can be integrated seamlessly, enabling the use of external plugins alongside native ones. This flexibility allows you to enhance the platform’s functionality without modifying its core structure. To add third-party dynamic plugins, you can either export them as standalone packages or wrap them in custom wrappers, especially if you want to adjust the plugin’s dependencies or configurations for compatibility. +In {product}, third-party dynamic plugins can be integrated seamlessly, enabling the use of external plugins alongside native ones. This flexibility allows you to enhance the platform functionality without modifying its core structure. To add third-party dynamic plugins, you can either export them as standalone packages or wrap them in custom wrappers, especially if you want to adjust the dependencies or configurations of a plugin for compatibility. The third-party plugins are typically packaged as dynamic plugins, which means they can be loaded at runtime, enabling you to easily manage external modules without rebuilding the entire application. The process involves creating a wrapper that exports the plugin code, ensuring that dependencies are correctly bundled or marked as shared, depending on their relationship to the {product-short} environment. @@ -24,13 +24,13 @@ The new backend system is created using `createBackendPlugin()` or `createBacken The backend plugins contains two types of dependencies, including: -* *Shared dependencies* are provided by the Backstage application and listed as `peerDependencies` in `package.json` file, not bundled in the dynamic plugin package. By default, all `@backstage` packages are shared. +* *Shared dependencies* are provided by an application and listed as `peerDependencies` in `package.json` file, not bundled in the dynamic plugin package. For example, by default, all `@backstage` packages are shared. + You can use the `--shared-package` flag to specify shared dependencies. To treat a `@backstage` package as private, use the negation prefix (`!`). * *Embedded dependencies* are bundled into the dynamic plugin package with their dependencies hoisted to the top level. By default, packages with `-node` or `-common` suffixes are embedded. + -You can use the `--embed-package` flag to specify additional embedded packages, including those in the same monorepo that do not follow the default naming convention. +You can use the `--embed-package` flag to specify additional embedded packages, including those in the same repository that do not follow the default naming convention. The following is an example of exporting a dynamic plugin with shared and embedded packages: @@ -44,10 +44,10 @@ npx @janus-idp/cli@latest export-dynamic-plugin --shared-package '!/@backstage/p <2> `@backstage/plugin-notifications-backend` package is marked as an embedded dependency and is bundled in the dynamic plugin package. -- -Frontend plugins:: +Front-end plugins:: + -- -Frontend plugins can leverage Scalprum for configuration, which the CLI can generate automatically during the export process. The generated default configuration is logged when running the following command: +Front-end plugins can use `scalprum` for configuration, which the CLI can generate automatically during the export process. The generated default configuration is logged when running the following command: .Example command to log the default configuration [source,bash] @@ -55,9 +55,9 @@ Frontend plugins can leverage Scalprum for configuration, which the CLI can gene npx @janus-idp/cli@latest export-dynamic ---- -The following is an example of default Scalprum configuration: +The following is an example of default `scalprum` configuration: -.Default Scalprum configuration +.Default `scalprum` configuration [source,json] ---- "scalprum": { @@ -68,9 +68,9 @@ The following is an example of default Scalprum configuration: } ---- -To customize Scalprum, add a `scalprum` section to the `package.json` file. For example: +You can add a `scalprum` section to the `package.json` file. For example: -.Example Scalprum customization +.Example `scalprum` customization [source,json] ---- "scalprum": { From 9b388825a66bcbdc7a692bf0a4189c512e20062d Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Wed, 4 Dec 2024 14:10:06 +0530 Subject: [PATCH 03/10] Incorporated review suggestions --- .../assembly-installing-rhdh-plugins.adoc | 4 +- ...mbly-third-party-plugins-installation.adoc | 101 ++-------------- .../proc-export-third-party-plugins-rhdh.adoc | 109 +++++++++++++++--- ...proc-install-third-party-plugins-rhdh.adoc | 28 +---- ...oc-package-third-party-dynamic-plugin.adoc | 2 +- ...ample-third-party-plugin-installation.adoc | 77 +++++++++++++ 6 files changed, 187 insertions(+), 134 deletions(-) create mode 100644 modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc diff --git a/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc index 5b43a141ac..c75f36088d 100644 --- a/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc @@ -10,9 +10,9 @@ include::../modules/dynamic-plugins/proc-config-dynamic-plugins-rhdh-operator.ad // Helm installation include::../modules/dynamic-plugins/con-install-dynamic-plugin-helm.adoc[leveloffset=+2] -include::../modules/dynamic-plugins/proc-obtaining-integrity-checksum.adoc[leveloffset=+3] +//include::../modules/dynamic-plugins/proc-obtaining-integrity-checksum.adoc[leveloffset=+3] //from tkral:This is documented in a better way in "= Installing third-party plugins in {product}" we can remove this module. It is not even placed correctly here as this is not specific to helm chart in anyway include::../modules/dynamic-plugins/ref-example-dynamic-plugin-helm-installations.adoc[leveloffset=+3] -include::../modules/dynamic-plugins/proc-rhdh-example-external-dynamic-plugins.adoc[leveloffset=+3] +//include::../modules/dynamic-plugins/proc-rhdh-example-external-dynamic-plugins.adoc[leveloffset=+3] assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc replaces this // Air gapped environment //include::../modules/dynamic-plugins/proc-rhdh-installing-external-dynamic-plugins-airgapped.adoc[leveloffset=+1] diff --git a/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc b/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc index eac1d88bc0..8407b17325 100644 --- a/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc +++ b/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc @@ -2,9 +2,9 @@ = Third-party plugins in {product} :context: assembly-third-party-plugins-installation -In {product}, third-party dynamic plugins can be integrated seamlessly, enabling the use of external plugins alongside native ones. This flexibility allows you to enhance the platform functionality without modifying its core structure. To add third-party dynamic plugins, you can either export them as standalone packages or wrap them in custom wrappers, especially if you want to adjust the dependencies or configurations of a plugin for compatibility. +In {product}, third-party dynamic plugins can be integrated seamlessly, enabling the use of external plugins. This flexibility allows you to enhance the platform functionality without modifying its source code and rebuilding. To add third-party dynamic plugins, you need to export them as derived package. -The third-party plugins are typically packaged as dynamic plugins, which means they can be loaded at runtime, enabling you to easily manage external modules without rebuilding the entire application. The process involves creating a wrapper that exports the plugin code, ensuring that dependencies are correctly bundled or marked as shared, depending on their relationship to the {product-short} environment. +The third-party plugins are typically packaged as dynamic plugin derived package, enabling you to manage external modules without rebuilding the entire application. The process involves exporting the plugin package, ensuring that dependencies are correctly bundled or marked as shared, depending on their relationship to the {product-short} environment. To integrate a third-party plugin into {product-short}: @@ -13,97 +13,6 @@ To integrate a third-party plugin into {product-short}: . Package and publish the dynamic plugin. See xref:proc-package-third-party-dynamic-plugin_{context}[]. . Install the plugin in the {product-short} environment. See xref:proc-install-third-party-plugins-rhdh_{context}[]. -The third-party plugins include: - -Backend plugins:: -+ --- -To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with, the new backend system. Additionally, these plugins must be rebuilt using a dedicated CLI command. - -The new backend system is created using `createBackendPlugin()` or `createBackendModule()`. You must export the new backend system as the default export from either the main package or an alpha package (if support exists in alpha). The dynamic export mechanism automatically identifies private dependencies, and adds them to the `bundleDependencies` field in the `package.json` file. This mechanism ensures that the dynamic plugin package is self-contained, with private dependencies bundled within a private `node_modules` folder. - -The backend plugins contains two types of dependencies, including: - -* *Shared dependencies* are provided by an application and listed as `peerDependencies` in `package.json` file, not bundled in the dynamic plugin package. For example, by default, all `@backstage` packages are shared. -+ -You can use the `--shared-package` flag to specify shared dependencies. To treat a `@backstage` package as private, use the negation prefix (`!`). - -* *Embedded dependencies* are bundled into the dynamic plugin package with their dependencies hoisted to the top level. By default, packages with `-node` or `-common` suffixes are embedded. -+ -You can use the `--embed-package` flag to specify additional embedded packages, including those in the same repository that do not follow the default naming convention. - -The following is an example of exporting a dynamic plugin with shared and embedded packages: - -.Example dynamic plugin export with shared and embedded packages -[source,bash] ----- -npx @janus-idp/cli@latest export-dynamic-plugin --shared-package '!/@backstage/plugin-notifications/'<1> --embed-package @backstage/plugin-notifications-backend <2> ----- - -<1> `@backstage/plugin-notifications` package is treated as a private dependency and is bundled in the dynamic plugin package, despite being in the `@backstage` scope. -<2> `@backstage/plugin-notifications-backend` package is marked as an embedded dependency and is bundled in the dynamic plugin package. --- - -Front-end plugins:: -+ --- -Front-end plugins can use `scalprum` for configuration, which the CLI can generate automatically during the export process. The generated default configuration is logged when running the following command: - -.Example command to log the default configuration -[source,bash] ----- -npx @janus-idp/cli@latest export-dynamic ----- - -The following is an example of default `scalprum` configuration: - -.Default `scalprum` configuration -[source,json] ----- -"scalprum": { - "name": "", // The Webpack container name matches the NPM package name, with "@" replaced by "." and "/" removed. - "exposedModules": { - "PluginRoot": "./src/index.ts" // The default module name is "PluginRoot" and doesn't need explicit specification in the app-config.yaml file. - } -} ----- - -You can add a `scalprum` section to the `package.json` file. For example: - -.Example `scalprum` customization -[source,json] ----- -"scalprum": { - "name": "custom-package-name", - "exposedModules": { - "FooModuleName": "./src/foo.ts", - "BarModuleName": "./src/bar.ts" - // Define multiple modules here, with each exposed as a separate entry point in the Webpack container. - } -} ----- - -Dynamic plugins might need adjustments for {product-short} needs, such as static JSX for mountpoints or dynamic routes. These changes are optional but might be incompatible with static plugins. - -To include static JSX, define an additional export and use it as the dynamic plugin's `importName`. For example: - -.Example static and dynamic plugin export -[source,tsx] ----- -// For a static plugin -export const EntityTechdocsContent = () => {...} - -// For a dynamic plugin -export const DynamicEntityTechdocsContent = { - element: EntityTechdocsContent, - staticJSXContent: ( - - - - ), -}; ----- --- //Export third-party plugins include::../modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc[leveloffset=+2] @@ -111,4 +20,8 @@ include::../modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc[le include::../modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc[leveloffset=+2] //install third-party plugins -include::../modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc[leveloffset=+2] \ No newline at end of file +include::../modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc[leveloffset=+2] + +//example third-party plugin installation +include::../modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc[leveloffset=+2] + diff --git a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc index 2ec942bf7f..0927b48dbc 100644 --- a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc +++ b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc @@ -1,7 +1,99 @@ [id="proc-export-third-party-plugins-rhdh_{context}"] = Exporting third-party plugins in {product} -To use dynamic plugins in {product}, the plugins must be exported as separate packages. These packages contain the plugin code and dependencies, ready for dynamic plugin integration into {product-short}. +To use plugins in {product}, the plugins must be exported as derived dynamic plugin package. These packages contain the plugin code and dependencies, ready for dynamic plugin integration into {product-short}. + +The third-party plugins include: + +Backend plugins:: ++ +-- +To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with the plugin instance. Additionally, these plugins must be rebuilt using a dedicated CLI command. + +The plugin instance is created using `createBackendPlugin()` or `createBackendModule()`. You must export the plugin instance as the default export from either the main package or an `alpha` package (if the plugin instance support is still provided using `alpha` APIs). This doesn't add any additional requirement on top of the standard plugin development guidelines of the plugin instance. + +Certain plugin dependencies require specific handling in the derived packages, such as: + +* *Shared dependencies* are provided by the {product-very-short} application and listed as `peerDependencies` in `package.json` file, not bundled in the dynamic plugin package. For example, by default, all `@backstage` scoped packages are shared. ++ +You can use the `--shared-package` flag to specify shared dependencies. To treat a `@backstage` package as private, use the negation prefix (`!`). + +* *Embedded dependencies* are bundled into the dynamic plugin package with their dependencies hoisted to the top level. By default, packages with `-node` or `-common` suffixes are embedded. ++ +You can use the `--embed-package` flag to specify additional embedded packages, including those in the same repository that do not follow the default naming convention. + +The following is an example of exporting a dynamic plugin with shared and embedded packages: + +.Example dynamic plugin export with shared and embedded packages +[source,bash] +---- +npx @janus-idp/cli@latest export-dynamic-plugin --shared-package '!/@backstage/plugin-notifications/'<1> --embed-package @backstage/plugin-notifications-backend <2> +---- + +<1> `@backstage/plugin-notifications` package is treated as a private dependency and is bundled in the dynamic plugin package, despite being in the `@backstage` scope. +<2> `@backstage/plugin-notifications-backend` package is marked as an embedded dependency and is bundled in the dynamic plugin package. +-- + +Front-end plugins:: ++ +-- +Front-end plugins can use `scalprum` for configuration, which the CLI can generate automatically during the export process. The generated default configuration is logged when running the following command: + +.Example command to log the default configuration +[source,bash] +---- +npx @janus-idp/cli@latest export-dynamic +---- + +The following is an example of default `scalprum` configuration: + +.Default `scalprum` configuration +[source,json] +---- +"scalprum": { + "name": "", // The Webpack container name matches the NPM package name, with "@" replaced by "." and "/" removed. + "exposedModules": { + "PluginRoot": "./src/index.ts" // The default module name is "PluginRoot" and doesn't need explicit specification in the app-config.yaml file. + } +} +---- + +You can add a `scalprum` section to the `package.json` file. For example: + +.Example `scalprum` customization +[source,json] +---- +"scalprum": { + "name": "custom-package-name", + "exposedModules": { + "FooModuleName": "./src/foo.ts", + "BarModuleName": "./src/bar.ts" + // Define multiple modules here, with each exposed as a separate entry point in the Webpack container. + } +} +---- + +Dynamic plugins might need adjustments for {product-short} needs, such as static JSX for mountpoints or dynamic routes. These changes are optional but might be incompatible with static plugins. + +To include static JSX, define an additional export and use it as the dynamic plugin's `importName`. For example: + +.Example static and dynamic plugin export +[source,tsx] +---- +// For a static plugin +export const EntityTechdocsContent = () => {...} + +// For a dynamic plugin +export const DynamicEntityTechdocsContent = { + element: EntityTechdocsContent, + staticJSXContent: ( + + + + ), +}; +---- +-- .Prerequisites * The `@janus-idp/cli` package is installed. Use the latest version (`@latest` tag) for compatibility with the most recent features and fixes. @@ -11,9 +103,8 @@ To use dynamic plugins in {product}, the plugins must be exported as separate pa * The third-party plugin is compatible with your {product} version. For more information, see link:https://github.com/janus-idp/backstage-showcase/blob/main/docs/dynamic-plugins/versions.md[Version compatibility matrix]. .Procedure -. Use the `package export-dynamic-plugin` command from the `@janus-idp/cli` package to export the plugin: -+ --- +Use the `package export-dynamic-plugin` command from the `@janus-idp/cli` package to export the plugin: + .Example command to export a third-party plugin [source,bash] ---- @@ -21,15 +112,5 @@ npx @janus-idp/cli@latest package export-dynamic-plugin ---- Ensure that you execute the previous command in the root directory of the plugin's JavaScript package (containing `package.json` file). --- -. Located the exported package in the `dist-dynamic` sub-folder. -. Use `npm pack` or a private NPM registry to package or distribute the plugin. For more information, see xref:proc-package-third-party-dynamic-plugin_{context}[]. -+ --- -[IMPORTANT] -==== -Ensure that you do not push derived dynamic plugin packages to a public NPM registry. Use a private NPM registry only. -==== --- diff --git a/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc index 307acabe04..c470922b9d 100644 --- a/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc +++ b/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc @@ -7,7 +7,7 @@ You can install a third-party plugins in {product} without rebuilding the {produ * The third-party plugin is packaged as a dynamic plugin in one of the following formats: ** OCI image ** TGZ file -** NPM or JavaScript package +** JavaScript package For more information about packaging a third-party plugin, see xref:proc-package-third-party-dynamic-plugin_{context}[]. @@ -41,7 +41,7 @@ plugins: ---- plugins: - disabled: false - package: oci://quay.io/example/image@sha256:! + package: oci://quay.io/example/image@sha256:28036abec4dffc714394e4ee433f16a59493db8017795049c831be41c02eb5dc!backstage-plugin-myplugin ---- . To apply the changes, restart the {product-very-short} application. @@ -50,16 +50,7 @@ plugins: Load a plugin packaged as a TGZ file:: + -- -. Specify the archive URL and its integrity hash in the `dynamic-plugins.default.yaml` file using the following format: -+ -.Configuration format in `dynamic-plugins.default.yaml` file -[source,yaml] ----- -plugins: - - disabled: false - package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz - integrity: ----- +. Specify the archive URL and its integrity hash in the `dynamic-plugins.default.yaml` file using the following example: + .Example configuration in `dynamic-plugins.default.yaml` file [source,yaml] @@ -73,27 +64,18 @@ plugins: . To apply the changes, restart the {product-very-short} application. -- -Load a plugin packaged as a JavaScript or NPM package:: +Load a plugin packaged as a JavaScript package:: + -- . Run the following command to obtain the integrity hash from the NPM registry: + [source,bash] ---- -npm view --registry @backstage-community/plugin-todo-dynamic@ dist.integrity +npm view --registry @ dist.integrity ---- . Specify the package name, version, and its integrity hash in the `dynamic-plugins.default.yaml` file as follows: + -.Configuration format in `dynamic-plugins.default.yaml` file -[source,yaml] ----- -plugins: - - disabled: false - package: @example/backstage-plugin-myplugin@1.0.0 - integrity: ----- -+ .Example configuration in `dynamic-plugins.default.yaml` file [source,yaml] ---- diff --git a/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc b/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc index 4ce75d728c..0698f47976 100644 --- a/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc +++ b/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc @@ -3,7 +3,7 @@ To package a third-party plugin as a dynamic plugin, you need to access to its source code and must export a plugin using the `@janus-idp/cli`. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. -After exporting a third-party plugin, you can convert the package into one of the following supported formats: +After exporting a third-party plugin, you can package the derived package into one of the following supported formats: * Open Container Initiative (OCI) image (recommended) * TGZ file diff --git a/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc b/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc new file mode 100644 index 0000000000..5ba4d1feaa --- /dev/null +++ b/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc @@ -0,0 +1,77 @@ +[id="ref-example-third-party-plugin-installation_{context}"] += Example of installing a third-party plugin in {product} + +This section provides step-by-step instructions for integrating the link:https://github.com/backstage/community-plugins/tree/main/workspaces/todo/plugins[Todo plugin] into your {product-short}. + +. *Obtain the third-party plugin source code*: Clone the plugins repository and navigate to the link:https://github.com/backstage/community-plugins/tree/main/workspaces/todo/plugins[Todo plugin] directory: ++ +-- +.Example commands to obtain the third-party plugin source code +[source,bash] +---- +$ git clone https://github.com/backstage/community-plugins +$ cd community-plugins/workspaces/todo +$ yarn install +---- +-- + +. *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: ++ +-- +.Example commands to export a backend plugin +[source,bash] +---- +$ cd todo-backend +$ npx @janus-idp/cli@latest package export-dynamic-plugin +---- + +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: + +.Example command to export a front-end plugin +[source,bash] +---- +$ cd ../todo +$ npx @janus-idp/cli@latest package export-dynamic-plugin +---- +-- + +. *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: ++ +-- +.Example commands to build an OCI image +[source,bash] +---- +$ cd ../.. +$ npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/user/backstage-community-plugin-todo:v0.1.1 +---- + +.Example command to push the OCI image to a container registry: +[source,bash] +---- +$ podman push quay.io/user/backstage-community-plugin-todo:v0.1.1 +---- +-- + +. *Install and configure the third-party plugin*: Add the following plugin definitions to your `dynamic-plugins.yaml` file: ++ +-- +.Example plugin definitions in `dynamic-plugins.yaml` file +[source,yaml] +---- +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 +---- +-- \ No newline at end of file From 734a5226d8ff6eef3a642ebac09d43e1c40310ed Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Thu, 5 Dec 2024 13:50:26 +0530 Subject: [PATCH 04/10] incorporated review suggestions --- .../proc-export-third-party-plugins-rhdh.adoc | 22 +++-- ...proc-install-third-party-plugins-rhdh.adoc | 25 +++-- ...oc-package-third-party-dynamic-plugin.adoc | 43 +++++---- ...ample-third-party-plugin-installation.adoc | 95 +++++++++++++++++-- 4 files changed, 146 insertions(+), 39 deletions(-) diff --git a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc index 0927b48dbc..befe2f64c9 100644 --- a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc +++ b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc @@ -3,24 +3,26 @@ To use plugins in {product}, the plugins must be exported as derived dynamic plugin package. These packages contain the plugin code and dependencies, ready for dynamic plugin integration into {product-short}. -The third-party plugins include: - Backend plugins:: + -- -To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with the plugin instance. Additionally, these plugins must be rebuilt using a dedicated CLI command. +To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with the new backend system. Additionally, these plugins must be rebuilt using a dedicated CLI command. + +The new backend system entry point (created using `createBackendPlugin()` or `createBackendModule()`) must be exported as the default export from either the main package or an `alpha` package (if the plugin instance support is still provided using `alpha` APIs). This doesn't add any additional requirement on top of the standard plugin development guidelines of the plugin instance. -The plugin instance is created using `createBackendPlugin()` or `createBackendModule()`. You must export the plugin instance as the default export from either the main package or an `alpha` package (if the plugin instance support is still provided using `alpha` APIs). This doesn't add any additional requirement on top of the standard plugin development guidelines of the plugin instance. +The dynamic export mechanism identifies private dependencies and sets the `bundleDependencies` field in the `package.json` file. This export mechanism ensures that the dynamic plugin package is published as a self-contained package, with its private dependencies bundled in a private `node_modules` folder. Certain plugin dependencies require specific handling in the derived packages, such as: * *Shared dependencies* are provided by the {product-very-short} application and listed as `peerDependencies` in `package.json` file, not bundled in the dynamic plugin package. For example, by default, all `@backstage` scoped packages are shared. + -You can use the `--shared-package` flag to specify shared dependencies. To treat a `@backstage` package as private, use the negation prefix (`!`). +You can use the `--shared-package` flag to specify shared dependencies, that are expected to be provided by {product} application and not bundled in the dynamic plugin package. ++ +To treat a `@backstage` package as private, use the negation prefix (`!`). For example, when a plugin depends on the package in `@backstage` that is not provided by the {product} application. * *Embedded dependencies* are bundled into the dynamic plugin package with their dependencies hoisted to the top level. By default, packages with `-node` or `-common` suffixes are embedded. + -You can use the `--embed-package` flag to specify additional embedded packages, including those in the same repository that do not follow the default naming convention. +You can use the `--embed-package` flag to specify additional embedded packages. For example, packages from the same workspace that do not follow the default naming convention. The following is an example of exporting a dynamic plugin with shared and embedded packages: @@ -99,7 +101,6 @@ export const DynamicEntityTechdocsContent = { * The `@janus-idp/cli` package is installed. Use the latest version (`@latest` tag) for compatibility with the most recent features and fixes. * The third-party plugin must have a valid package.json file in its root directory, containing all required metadata and dependencies. * Node.js and NPM is installed and configured. -* You have access to a private NPM registry for publishing and distributing the exported plugin package. * The third-party plugin is compatible with your {product} version. For more information, see link:https://github.com/janus-idp/backstage-showcase/blob/main/docs/dynamic-plugins/versions.md[Version compatibility matrix]. .Procedure @@ -113,4 +114,11 @@ npx @janus-idp/cli@latest package export-dynamic-plugin Ensure that you execute the previous command in the root directory of the plugin's JavaScript package (containing `package.json` file). +The resulting derived package will be located in the `dist-dynamic` subfolder. The exported package name consists of the original plugin name with `-dynamic` appended. + +[WARNING] +==== +The derived dynamic plugin JavaScript packages must not be published to the public NPM registry. For more appropriate packaging options, see xref:proc-package-third-party-dynamic-plugin_{context}[]. If you must publish to the NPM registry, use a private registry. +==== + diff --git a/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc index c470922b9d..65b0c96fd8 100644 --- a/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc +++ b/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc @@ -3,6 +3,15 @@ You can install a third-party plugins in {product} without rebuilding the {product-very-short} application. +The location of the `dynamic-plugin-config.yaml` file depends on the deployment method. For more details, refer to xref:proc-config-dynamic-plugins-rhdh-operator_{context}[] and xref:con-install-dynamic-plugin-helm_{context}[]. + +Plugins are defined in the `plugins` array within the `dynamic-plugin-config.yaml` file. Each plugin is represented as an object with the following properties: + +* `package`: The plugin's package definition, which can be an OCI image, a TGZ file, a JavaScript package, or a directory path +* `disabled`: A boolean value indicating whether the plugin is enabled or disabled. +* `integrity`: The integrity hash of the package, required for TGZ file and JavaScript packages. +* `pluginConfig`: The plugin's configuration. For backend plugins, this is optional; for frontend plugins, it is required. The `pluginConfig` is a fragment of the `app-config.yaml` file, and any added properties are merged with the {product-very-short} `app-config.yaml` file. + .Prerequisites * The third-party plugin is packaged as a dynamic plugin in one of the following formats: ** OCI image @@ -20,11 +29,11 @@ You can also load dynamic plugins from a plain directory, though this is intende Load a plugin packaged as an OCI image:: + -- -. Define the plugin with the `oci://` prefix in the following format in `dynamic-plugins.default.yaml` file: +. Define the plugin with the `oci://` prefix in the following format in `dynamic-plugins.yaml` file: + `oci://:!` + -.Example configuration in `dynamic-plugins.default.yaml` file +.Example configuration in `dynamic-plugins.yaml` file [source,yaml] ---- plugins: @@ -34,9 +43,9 @@ plugins: . 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`. -. To perform an integrity check, use the image digest in place of the tag in `dynamic-plugins.default.yaml` file as follows: +. To perform an integrity check, use the image digest in place of the tag in `dynamic-plugins.yaml` file as follows: + -.Example configuration in `dynamic-plugins.default.yaml` file +.Example configuration in `dynamic-plugins.yaml` file [source,yaml] ---- plugins: @@ -50,9 +59,9 @@ plugins: Load a plugin packaged as a TGZ file:: + -- -. Specify the archive URL and its integrity hash in the `dynamic-plugins.default.yaml` file using the following example: +. Specify the archive URL and its integrity hash in the `dynamic-plugins.yaml` file using the following example: + -.Example configuration in `dynamic-plugins.default.yaml` file +.Example configuration in `dynamic-plugins.yaml` file [source,yaml] ---- plugins: @@ -74,9 +83,9 @@ Load a plugin packaged as a JavaScript package:: npm view --registry @ dist.integrity ---- -. Specify the package name, version, and its integrity hash in the `dynamic-plugins.default.yaml` file as follows: +. Specify the package name, version, and its integrity hash in the `dynamic-plugins.yaml` file as follows: + -.Example configuration in `dynamic-plugins.default.yaml` file +.Example configuration in `dynamic-plugins.yaml` file [source,yaml] ---- plugins: diff --git a/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc b/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc index 0698f47976..c69861c611 100644 --- a/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc +++ b/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc @@ -14,15 +14,15 @@ After exporting a third-party plugin, you can package the derived package into o Exported dynamic plugin packages must only be published to private NPM registries. ==== -[#convert-to-oci-image] -== Converting a dynamic plugin package to an OCI image +[#create-oci-image] +== Creating an OCI image with dynamic packages .Prerequisites * You have installed `podman` or `docker`. * You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. .Procedure -. Navigate to the exported plugin's root directory (not the `dist-dynamic` directory). +. Navigate to the plugin's root directory (not the `dist-dynamic` directory). . Run the following command to package the plugin into an OCI image: + -- @@ -49,11 +49,11 @@ podman push quay.io/example/image:v0.0.1 docker push quay.io/example/image:v0.0.1 ---- -The output of the previous commands provides the plugin's path for use in the `dynamic-plugin-config.yaml` file. +The output of the `package-dynamic-plugins` command provides the plugin's path for use in the `dynamic-plugin-config.yaml` file. -- -[#convert-to-tgz] -== Converting a dynamic plugin package to a TGZ file +[#create-tgz-file] +== Creating a TGZ file with dynamic packages .Prerequisites * You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. @@ -68,16 +68,15 @@ The output of the previous commands provides the plugin's path for use in the `d ---- npm pack ---- --- -. To retrieve the integrity hash of the archive, run the following command: -+ --- -.Example command to retrieve the integrity hash of a `tgz` archive +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 [source,bash] ---- -npm pack --json | jq -r '.[0].integrity' +npm pack --json | head -n 10 ---- -- + . Host the archive on a web server accessible to your {product-very-short} instance, and reference its URL in the `dynamic-plugin-config.yaml` file as follows: + -- @@ -97,10 +96,11 @@ plugins: ---- npm pack --pack-destination ~/test/dynamic-plugins-root/ ---- --- -. Build and deploy an HTTP server in {ocp-short}: -+ --- + +[TIP] +==== +To create a plugin registry using HTTP server on {ocp-short}, run the following commands: + .Example commands to build and deploy an HTTP server in {ocp-short} [source,bash] ---- @@ -109,7 +109,9 @@ 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 ---- +==== -- + . Configure your {product-very-short} to use plugins from the HTTP server by editing the `dynamic-plugin-config.yaml` file: + -- @@ -121,8 +123,13 @@ plugins: ---- -- -[#convert-to-jsp] -== Converting a dynamic plugin to a JavaScript package +[#create-js-package] +== Creating a JavaScript package with dynamic packages + +[WARNING] +==== +The derived dynamic plugin JavaScript packages must not be published to the public NPM registry. If you must publish to the NPM registry, use a private registry. +==== .Prerequisites * You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. diff --git a/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc b/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc index 5ba4d1feaa..8444d74e3f 100644 --- a/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc +++ b/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc @@ -6,7 +6,7 @@ This section provides step-by-step instructions for integrating the link:https:/ . *Obtain the third-party plugin source code*: Clone the plugins repository and navigate to the link:https://github.com/backstage/community-plugins/tree/main/workspaces/todo/plugins[Todo plugin] directory: + -- -.Example commands to obtain the third-party plugin source code +.Obtain the third-party plugin source code [source,bash] ---- $ git clone https://github.com/backstage/community-plugins @@ -18,44 +18,127 @@ $ yarn install . *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: + -- -.Example commands to export a backend plugin +.Export a backend plugin [source,bash] ---- $ cd todo-backend $ npx @janus-idp/cli@latest package export-dynamic-plugin ---- +.Output of exporting a backend plugin commands +[source,bash] +---- +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: -.Example command to export a front-end plugin +.Export a front-end plugin [source,bash] ---- $ cd ../todo $ npx @janus-idp/cli@latest package export-dynamic-plugin ---- + +.Output of exporting a front-end plugin commands +[source,bash] +---- +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 +---- -- . *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: + -- -.Example commands to build an OCI image +.Build an OCI image [source,bash] ---- $ cd ../.. $ npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/user/backstage-community-plugin-todo:v0.1.1 ---- -.Example command to push the OCI image to a container registry: +.Output of building an OCI image commands +[source,bash] +---- + 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: [source,bash] ---- $ podman push quay.io/user/backstage-community-plugin-todo:v0.1.1 ---- + +.Output of pushing the OCI image command +[source,bash] +---- +Getting image source signatures +Copying blob sha256:86a372c456ae6a7a305cd464d194aaf03660932efd53691998ab3403f87cacb5 +Copying config sha256:3b7f074856ecfbba95a77fa87cfad341e8a30c7069447de8144aea0edfcb603e +Writing manifest to image destination +---- -- . *Install and configure the third-party plugin*: Add the following plugin definitions to your `dynamic-plugins.yaml` file: + -- -.Example plugin definitions in `dynamic-plugins.yaml` file +.Plugin definitions in `dynamic-plugins.yaml` file [source,yaml] ---- packages: From 73ef08ed5a4af5a12e332079816729f6cc22222c Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Thu, 5 Dec 2024 13:58:07 +0530 Subject: [PATCH 05/10] fixed links and added context to install plugin assembly --- .../dynamic-plugins/assembly-installing-rhdh-plugins.adoc | 1 + .../dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc index c75f36088d..35e1ee5816 100644 --- a/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc @@ -1,5 +1,6 @@ [id="rhdh-installing-rhdh-plugins_{context}"] = Installing dynamic plugins in {product} +:context: rhdh-installing-rhdh-plugins The dynamic plugin support is based on the backend plugin manager package, which is a service that scans a configured root directory (`dynamicPlugins.rootDirectory` in the `app-config.yaml` file) for dynamic plugin packages and loads them dynamically. diff --git a/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc index 65b0c96fd8..02830f525a 100644 --- a/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc +++ b/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc @@ -3,7 +3,7 @@ You can install a third-party plugins in {product} without rebuilding the {product-very-short} application. -The location of the `dynamic-plugin-config.yaml` file depends on the deployment method. For more details, refer to xref:proc-config-dynamic-plugins-rhdh-operator_{context}[] and xref:con-install-dynamic-plugin-helm_{context}[]. +The location of the `dynamic-plugin-config.yaml` file depends on the deployment method. For more details, refer to xref:proc-config-dynamic-plugins-rhdh-operator_rhdh-installing-rhdh-plugins[] and xref:con-install-dynamic-plugin-helm_rhdh-installing-rhdh-plugins[]. Plugins are defined in the `plugins` array within the `dynamic-plugin-config.yaml` file. Each plugin is represented as an object with the following properties: From e272fc83e4f334dec698dc631224918b464baf6c Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Tue, 10 Dec 2024 14:08:45 +0530 Subject: [PATCH 06/10] review suggestions incorporated --- ...mbly-install-third-party-plugins-rhdh.adoc | 32 ++++ ...ge-publish-third-party-dynamic-plugin.adoc | 23 +++ ...mbly-third-party-plugins-installation.adoc | 27 --- .../assembly-third-party-plugins.adoc | 26 +++ .../proc-create-plugin-js-package.adoc | 39 +++++ .../proc-create-plugin-oci-image.adoc | 37 ++++ .../proc-create-plugin-tgz-file.adoc | 70 ++++++++ .../proc-export-third-party-plugins-rhdh.adoc | 4 +- ...proc-install-third-party-plugins-rhdh.adoc | 129 -------------- .../proc-load-plugin-js-package.adoc | 67 +++++++ .../proc-load-plugin-oci-image.adoc | 38 ++++ .../proc-load-plugin-tgz-file.adoc | 24 +++ ...oc-package-third-party-dynamic-plugin.adoc | 165 ------------------ ...ample-third-party-plugin-installation.adoc | 10 +- titles/plugins-rhdh-install/master.adoc | 2 +- 15 files changed, 364 insertions(+), 329 deletions(-) create mode 100644 assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc create mode 100644 assemblies/dynamic-plugins/assembly-package-publish-third-party-dynamic-plugin.adoc delete mode 100644 assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc create mode 100644 assemblies/dynamic-plugins/assembly-third-party-plugins.adoc create mode 100644 modules/dynamic-plugins/proc-create-plugin-js-package.adoc create mode 100644 modules/dynamic-plugins/proc-create-plugin-oci-image.adoc create mode 100644 modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc delete mode 100644 modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc create mode 100644 modules/dynamic-plugins/proc-load-plugin-js-package.adoc create mode 100644 modules/dynamic-plugins/proc-load-plugin-oci-image.adoc create mode 100644 modules/dynamic-plugins/proc-load-plugin-tgz-file.adoc delete mode 100644 modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc diff --git a/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc b/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc new file mode 100644 index 0000000000..11423d617c --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc @@ -0,0 +1,32 @@ +[id="assembly-install-third-party-plugins-rhdh"] += Installing third-party plugins in {product} +:context: assembly-install-third-party-plugins-rhdh + +You can install a third-party plugins in {product} without rebuilding the {product-very-short} application. + +The location of the `dynamic-plugin-config.yaml` file depends on the deployment method. For more details, refer to xref:proc-config-dynamic-plugins-rhdh-operator_rhdh-installing-rhdh-plugins[] and xref:con-install-dynamic-plugin-helm_rhdh-installing-rhdh-plugins[]. + +Plugins are defined in the `plugins` array within the `dynamic-plugin-config.yaml` file. Each plugin is represented as an object with the following properties: + +* `package`: The plugin's package definition, which can be an OCI image, a TGZ file, a JavaScript package, or a directory path +* `disabled`: A boolean value indicating whether the plugin is enabled or disabled. +* `integrity`: The integrity hash of the package, required for TGZ file and JavaScript packages. +* `pluginConfig`: The plugin's configuration. For backend plugins, this is optional; for frontend plugins, it is required. The `pluginConfig` is a fragment of the `app-config.yaml` file, and any added properties are merged with the {product-very-short} `app-config.yaml` file. + +[NOTE] +==== +You can also load dynamic plugins from a plain directory, though this is intended for development or testing purposes and is not recommended for production, except for plugins included in the {product-very-short} container image. +==== + +//OCI image +include::../modules/dynamic-plugins/proc-load-plugin-oci-image.adoc[leveloffset=+2] + +//TGZ file +include::../modules/dynamic-plugins/proc-load-plugin-tgz-file.adoc[leveloffset=+2] + +//JavaScript package +include::../modules/dynamic-plugins/proc-load-plugin-js-package.adoc[leveloffset=+2] + +//example third-party plugin installation +include::../modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc[leveloffset=+2] + diff --git a/assemblies/dynamic-plugins/assembly-package-publish-third-party-dynamic-plugin.adoc b/assemblies/dynamic-plugins/assembly-package-publish-third-party-dynamic-plugin.adoc new file mode 100644 index 0000000000..699b67bb8c --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-package-publish-third-party-dynamic-plugin.adoc @@ -0,0 +1,23 @@ +[id="assembly-package-publish-third-party-dynamic-plugin"] += Packaging and publishing third-party plugins as dynamic plugins +:context: assembly-package-publish-third-party-dynamic-plugin + +After xref:proc-export-third-party-plugins-rhdh_assembly-third-party-plugins[exporting a third-party plugin], you can package the derived package into one of the following supported formats: + +* Open Container Initiative (OCI) image (recommended) +* TGZ file +* JavaScript package + +[IMPORTANT] +==== +Exported dynamic plugin packages must only be published to private NPM registries. +==== + +//OCI image +include::../modules/dynamic-plugins/proc-create-plugin-oci-image.adoc[leveloffset=+2] + +//TGZ file +include::../modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc[leveloffset=+2] + +//JavaScript package +include::../modules/dynamic-plugins/proc-create-plugin-js-package.adoc[leveloffset=+2] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc b/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc deleted file mode 100644 index 8407b17325..0000000000 --- a/assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc +++ /dev/null @@ -1,27 +0,0 @@ -[id="assembly-third-party-plugins-installation"] -= Third-party plugins in {product} -:context: assembly-third-party-plugins-installation - -In {product}, third-party dynamic plugins can be integrated seamlessly, enabling the use of external plugins. This flexibility allows you to enhance the platform functionality without modifying its source code and rebuilding. To add third-party dynamic plugins, you need to export them as derived package. - -The third-party plugins are typically packaged as dynamic plugin derived package, enabling you to manage external modules without rebuilding the entire application. The process involves exporting the plugin package, ensuring that dependencies are correctly bundled or marked as shared, depending on their relationship to the {product-short} environment. - -To integrate a third-party plugin into {product-short}: - -. First, obtain the plugin's source code. -. Export the plugin as a dynamic plugin package. See xref:proc-export-third-party-plugins-rhdh_{context}[]. -. Package and publish the dynamic plugin. See xref:proc-package-third-party-dynamic-plugin_{context}[]. -. Install the plugin in the {product-short} environment. See xref:proc-install-third-party-plugins-rhdh_{context}[]. - -//Export third-party plugins -include::../modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc[leveloffset=+2] - -//package and publish third-party plugins -include::../modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc[leveloffset=+2] - -//install third-party plugins -include::../modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc[leveloffset=+2] - -//example third-party plugin installation -include::../modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc[leveloffset=+2] - diff --git a/assemblies/dynamic-plugins/assembly-third-party-plugins.adoc b/assemblies/dynamic-plugins/assembly-third-party-plugins.adoc new file mode 100644 index 0000000000..ef5c1c4f05 --- /dev/null +++ b/assemblies/dynamic-plugins/assembly-third-party-plugins.adoc @@ -0,0 +1,26 @@ +[id="assembly-third-party-plugins"] += Third-party plugins in {product} +:context: assembly-third-party-plugins + +You can integrate third-party dynamic plugins in {product}. This flexibility allows you to enhance the platform functionality without modifying its source code and rebuilding. To add third-party dynamic plugins, you can export them as derived package. + +While exporting the plugin package, you must ensure that dependencies are correctly bundled or marked as shared, depending on their relationship to the {product-short} environment. + +To integrate a third-party plugin into {product-short}: + +. First, obtain the plugin's source code. +. Export the plugin as a dynamic plugin package. See xref:proc-export-third-party-plugins-rhdh_assembly-third-party-plugins[]. +. Package and publish the dynamic plugin. See xref:assembly-package-publish-third-party-dynamic-plugin[]. +. Install the plugin in the {product-short} environment. See xref:assembly-install-third-party-plugins-rhdh[]. + +//Export third-party plugins +include::../modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc[leveloffset=+2] + +//package and publish third-party plugins +include::assembly-package-publish-third-party-dynamic-plugin.adoc[leveloffset=+1] + +//Install third-party plugin +include::assembly-install-third-party-plugins-rhdh.adoc[leveloffset=+1] + + + diff --git a/modules/dynamic-plugins/proc-create-plugin-js-package.adoc b/modules/dynamic-plugins/proc-create-plugin-js-package.adoc new file mode 100644 index 0000000000..9f0e882ab9 --- /dev/null +++ b/modules/dynamic-plugins/proc-create-plugin-js-package.adoc @@ -0,0 +1,39 @@ +[id="proc-create-plugin-js-package_{context}"] += Creating a JavaScript package with dynamic packages + +[WARNING] +==== +The derived dynamic plugin JavaScript packages must not be published to the public NPM registry. If you must publish to the NPM registry, use a private registry. +==== + +.Prerequisites +* You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_assembly-third-party-plugins[]. + +.Procedure +. Navigate to the `dist-dynamic` directory. +. Run the following command to publish the package to your private NPM registry: ++ +-- +.Example command to publish a plugin package to an NPM registry +[source,bash] +---- +npm publish --registry +---- + +[TIP] +==== +You can add the following to your `package.json` file before running the `export` command: + +.Example `package.json` file +[source,json] +---- +{ + "publishConfig": { + "registry": "" + } +} +---- + +If you modify the `publishConfig` after exporting the dynamic plugin, re-run the `export-dynamic-plugin` command to ensure the correct configuration is included. +==== +-- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-create-plugin-oci-image.adoc b/modules/dynamic-plugins/proc-create-plugin-oci-image.adoc new file mode 100644 index 0000000000..a332d012a6 --- /dev/null +++ b/modules/dynamic-plugins/proc-create-plugin-oci-image.adoc @@ -0,0 +1,37 @@ +[id="proc-create-plugin-oci-image_{context}"] += Creating an OCI image with dynamic packages + +.Prerequisites +* You have installed `podman` or `docker`. +* You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_assembly-third-party-plugins[]. + +.Procedure +. Navigate to the plugin's root directory (not the `dist-dynamic` directory). +. Run the following command to package the plugin into an OCI image: ++ +-- +.Example command to package an exported third-party plugin +[source,bash] +---- +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. +-- +. Run one of the following commands to push the image to a registry: ++ +-- +.Example command to push an image to a registry using podman +[source,bash] +---- +podman push quay.io/example/image:v0.0.1 +---- + +.Example command to push an image to a registry using docker +[source,bash] +---- +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. +-- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc b/modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc new file mode 100644 index 0000000000..199d710119 --- /dev/null +++ b/modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc @@ -0,0 +1,70 @@ +[id="proc-create-plugin-tgz-file_{context}"] += Creating a TGZ file with dynamic packages + +.Prerequisites +* You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_assembly-third-party-plugins[]. + +.Procedure +. Navigate to the `dist-dynamic` directory. +. Run the following command to create a `tgz` archive: ++ +-- +.Example command to create a `tgz` archive +[source,bash] +---- +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 +[source,bash] +---- +npm pack --json | head -n 10 +---- +-- + +. Host the archive on a web server accessible to your {product-very-short} instance, and reference its URL in the `dynamic-plugin-config.yaml` file as follows: ++ +-- +.Example `dynamic-plugin-config.yaml` file +[source,yaml] +---- +plugins: + - package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz + integrity: sha512- +---- +-- +. Run the following command to package the plugins: ++ +-- +.Example command to package a dynamic plugin +[source,bash] +---- +npm pack --pack-destination ~/test/dynamic-plugins-root/ +---- + +[TIP] +==== +To create a plugin registry using HTTP server on {ocp-short}, run the following commands: + +.Example commands to build and deploy an HTTP server in {ocp-short} +[source,bash] +---- +oc project rhdh +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 +---- +==== +-- + +. Configure your {product-very-short} to use plugins from the HTTP server by editing the `dynamic-plugin-config.yaml` file: ++ +-- +.Example configuration to use packaged plugins in {product-very-short} +[source,yaml] +---- +plugins: + - package: http://plugin-registry:8080/backstage-plugin-myplugin-1.9.6.tgz +---- +-- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc index befe2f64c9..cce204fbef 100644 --- a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc +++ b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc @@ -1,7 +1,7 @@ [id="proc-export-third-party-plugins-rhdh_{context}"] = Exporting third-party plugins in {product} -To use plugins in {product}, the plugins must be exported as derived dynamic plugin package. These packages contain the plugin code and dependencies, ready for dynamic plugin integration into {product-short}. +To use plugins in {product}, you can export plugins as derived dynamic plugin packages. These packages contain the plugin code and dependencies, ready for dynamic plugin integration into {product-short}. Backend plugins:: + @@ -118,7 +118,7 @@ The resulting derived package will be located in the `dist-dynamic` subfolder. T [WARNING] ==== -The derived dynamic plugin JavaScript packages must not be published to the public NPM registry. For more appropriate packaging options, see xref:proc-package-third-party-dynamic-plugin_{context}[]. If you must publish to the NPM registry, use a private registry. +The derived dynamic plugin JavaScript packages must not be published to the public NPM registry. For more appropriate packaging options, see xref:assembly-package-publish-third-party-dynamic-plugin[]. If you must publish to the NPM registry, use a private registry. ==== diff --git a/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc deleted file mode 100644 index 02830f525a..0000000000 --- a/modules/dynamic-plugins/proc-install-third-party-plugins-rhdh.adoc +++ /dev/null @@ -1,129 +0,0 @@ -[id="proc-install-third-party-plugins-rhdh_{context}"] -= Installing third-party plugins in {product} - -You can install a third-party plugins in {product} without rebuilding the {product-very-short} application. - -The location of the `dynamic-plugin-config.yaml` file depends on the deployment method. For more details, refer to xref:proc-config-dynamic-plugins-rhdh-operator_rhdh-installing-rhdh-plugins[] and xref:con-install-dynamic-plugin-helm_rhdh-installing-rhdh-plugins[]. - -Plugins are defined in the `plugins` array within the `dynamic-plugin-config.yaml` file. Each plugin is represented as an object with the following properties: - -* `package`: The plugin's package definition, which can be an OCI image, a TGZ file, a JavaScript package, or a directory path -* `disabled`: A boolean value indicating whether the plugin is enabled or disabled. -* `integrity`: The integrity hash of the package, required for TGZ file and JavaScript packages. -* `pluginConfig`: The plugin's configuration. For backend plugins, this is optional; for frontend plugins, it is required. The `pluginConfig` is a fragment of the `app-config.yaml` file, and any added properties are merged with the {product-very-short} `app-config.yaml` file. - -.Prerequisites -* The third-party plugin is packaged as a dynamic plugin in one of the following formats: -** OCI image -** TGZ file -** JavaScript package - -For more information about packaging a third-party plugin, see xref:proc-package-third-party-dynamic-plugin_{context}[]. - -[NOTE] -==== -You can also load dynamic plugins from a plain directory, though this is intended for development or testing purposes and is not recommended for production, except for plugins included in the {product-very-short} container image. -==== - -.Procedure -Load a plugin packaged as an OCI image:: -+ --- -. Define the plugin with the `oci://` prefix in the following format in `dynamic-plugins.yaml` file: -+ -`oci://:!` -+ -.Example configuration in `dynamic-plugins.yaml` file -[source,yaml] ----- -plugins: - - disabled: false - package: oci://quay.io/example/image:v0.0.1!backstage-plugin-myplugin ----- - -. 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`. - -. To perform an integrity check, use the image digest in place of the tag in `dynamic-plugins.yaml` file as follows: -+ -.Example configuration in `dynamic-plugins.yaml` file -[source,yaml] ----- -plugins: - - disabled: false - package: oci://quay.io/example/image@sha256:28036abec4dffc714394e4ee433f16a59493db8017795049c831be41c02eb5dc!backstage-plugin-myplugin ----- - -. To apply the changes, restart the {product-very-short} application. --- - -Load a plugin packaged as a TGZ file:: -+ --- -. 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 -[source,yaml] ----- -plugins: - - disabled: false - package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz - integrity: sha512-9WlbgEdadJNeQxdn1973r5E4kNFvnT9GjLD627GWgrhCaxjCmxqdNW08cj+Bf47mwAtZMt1Ttyo+ZhDRDj9PoA== ----- - -. To apply the changes, restart the {product-very-short} application. --- - -Load a plugin packaged as a JavaScript package:: -+ --- -. Run the following command to obtain the integrity hash from the NPM registry: -+ -[source,bash] ----- -npm view --registry @ dist.integrity ----- - -. Specify the package name, version, and its integrity hash in the `dynamic-plugins.yaml` file as follows: -+ -.Example configuration in `dynamic-plugins.yaml` file -[source,yaml] ----- -plugins: - - disabled: false - package: @example/backstage-plugin-myplugin@1.0.0 - integrity: sha512-9WlbgEdadJNeQxdn1973r5E4kNFvnT9GjLD627GWgrhCaxjCmxqdNW08cj+Bf47mwAtZMt1Ttyo+ZhDRDj9PoA== ----- - -. If you are using a custom NPM registry, create a `.npmrc` file with the registry URL and authentication details: -+ -.Example code for `.npmrc` file -[source,text] ----- -registry= -//:_authToken= ----- - -. When using {ocp-short} or Kubernetes: -+ -* Create a secret with the `.npmrc` content as follows: -+ -.Example secret configuration -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: dynamic-plugins-npmrc -type: Opaque -stringData: - .npmrc: | - registry= - //:_authToken= ----- - -* For {product-very-short} Helm chart, name the secret using the following format for automatic mounting: -+ -`-dynamic-plugins-npmrc` - -. To apply the changes, restart the {product-very-short} application. --- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-load-plugin-js-package.adoc b/modules/dynamic-plugins/proc-load-plugin-js-package.adoc new file mode 100644 index 0000000000..fe8cbafa09 --- /dev/null +++ b/modules/dynamic-plugins/proc-load-plugin-js-package.adoc @@ -0,0 +1,67 @@ +[id="proc-load-plugin-js-package_{context}"] += Loading a plugin packaged as a JavaScript package + +.Prerequisites +* The third-party plugin is packaged as a dynamic plugin in a JavaScript package. ++ +For more information about packaging a third-party plugin, see xref:assembly-package-publish-third-party-dynamic-plugin[]. + +.Procedure +. Run the following command to obtain the integrity hash from the NPM registry: ++ +-- +[source,bash] +---- +npm view --registry @ dist.integrity +---- +-- + +. Specify the package name, version, and its integrity hash in the `dynamic-plugins.yaml` file as follows: ++ +-- +.Example configuration in `dynamic-plugins.yaml` file +[source,yaml] +---- +plugins: + - disabled: false + package: @example/backstage-plugin-myplugin@1.0.0 + integrity: sha512-9WlbgEdadJNeQxdn1973r5E4kNFvnT9GjLD627GWgrhCaxjCmxqdNW08cj+Bf47mwAtZMt1Ttyo+ZhDRDj9PoA== +---- +-- + +. If you are using a custom NPM registry, create a `.npmrc` file with the registry URL and authentication details: ++ +-- +.Example code for `.npmrc` file +[source,text] +---- +registry= +//:_authToken= +---- +-- + +. When using {ocp-short} or Kubernetes: ++ +-- +* Create a secret with the `.npmrc` content as follows: ++ +.Example secret configuration +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + name: dynamic-plugins-npmrc +type: Opaque +stringData: + .npmrc: | + registry= + //:_authToken= +---- + +* For {product-very-short} Helm chart, name the secret using the following format for automatic mounting: ++ +`-dynamic-plugins-npmrc` +-- + +. To apply the changes, restart the {product-very-short} application. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-load-plugin-oci-image.adoc b/modules/dynamic-plugins/proc-load-plugin-oci-image.adoc new file mode 100644 index 0000000000..4045d86f58 --- /dev/null +++ b/modules/dynamic-plugins/proc-load-plugin-oci-image.adoc @@ -0,0 +1,38 @@ +[id="proc-load-plugin-oci-image_{context}"] += Loading a plugin packaged as an OCI image + +.Prerequisites +* The third-party plugin is packaged as a dynamic plugin in an OCI image. ++ +For more information about packaging a third-party plugin, see xref:assembly-package-publish-third-party-dynamic-plugin[]. + +.Procedure +. Define the plugin with the `oci://` prefix in the following format in `dynamic-plugins.yaml` file: ++ +-- +`oci://:!` + +.Example configuration in `dynamic-plugins.yaml` file +[source,yaml] +---- +plugins: + - disabled: false + package: oci://quay.io/example/image:v0.0.1!backstage-plugin-myplugin +---- +-- + +. 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`. + +. To perform an integrity check, use the image digest in place of the tag in `dynamic-plugins.yaml` file as follows: ++ +-- +.Example configuration in `dynamic-plugins.yaml` file +[source,yaml] +---- +plugins: + - disabled: false + package: oci://quay.io/example/image@sha256:28036abec4dffc714394e4ee433f16a59493db8017795049c831be41c02eb5dc!backstage-plugin-myplugin +---- +-- + +. To apply the changes, restart the {product-very-short} application. diff --git a/modules/dynamic-plugins/proc-load-plugin-tgz-file.adoc b/modules/dynamic-plugins/proc-load-plugin-tgz-file.adoc new file mode 100644 index 0000000000..d8b07b6a37 --- /dev/null +++ b/modules/dynamic-plugins/proc-load-plugin-tgz-file.adoc @@ -0,0 +1,24 @@ +[id="proc-load-plugin-tgz-file_{context}"] += Loading a plugin packaged as a TGZ file + +.Prerequisites +* The third-party plugin is packaged as a dynamic plugin in a TGZ file. ++ +For more information about packaging a third-party plugin, see xref:assembly-package-publish-third-party-dynamic-plugin[]. + +.Procedure + +. 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 +[source,yaml] +---- +plugins: + - disabled: false + package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz + integrity: sha512-9WlbgEdadJNeQxdn1973r5E4kNFvnT9GjLD627GWgrhCaxjCmxqdNW08cj+Bf47mwAtZMt1Ttyo+ZhDRDj9PoA== +---- +-- + +. To apply the changes, restart the {product-very-short} application. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc b/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc deleted file mode 100644 index c69861c611..0000000000 --- a/modules/dynamic-plugins/proc-package-third-party-dynamic-plugin.adoc +++ /dev/null @@ -1,165 +0,0 @@ -[id="proc-package-third-party-dynamic-plugin_{context}"] -= Packaging and publishing third-party plugins as dynamic plugins - -To package a third-party plugin as a dynamic plugin, you need to access to its source code and must export a plugin using the `@janus-idp/cli`. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. - -After exporting a third-party plugin, you can package the derived package into one of the following supported formats: - -* Open Container Initiative (OCI) image (recommended) -* TGZ file -* JavaScript package - -[IMPORTANT] -==== -Exported dynamic plugin packages must only be published to private NPM registries. -==== - -[#create-oci-image] -== Creating an OCI image with dynamic packages - -.Prerequisites -* You have installed `podman` or `docker`. -* You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. - -.Procedure -. Navigate to the plugin's root directory (not the `dist-dynamic` directory). -. Run the following command to package the plugin into an OCI image: -+ --- -.Example command to package an exported third-party plugin -[source,bash] ----- -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. --- -. Run one of the following commands to push the image to a registry: -+ --- -.Example command to push an image to a registry using podman -[source,bash] ----- -podman push quay.io/example/image:v0.0.1 ----- - -.Example command to push an image to a registry using docker -[source,bash] ----- -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. --- - -[#create-tgz-file] -== Creating a TGZ file with dynamic packages - -.Prerequisites -* You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. - -.Procedure -. Navigate to the `dist-dynamic` directory. -. Run the following command to create a `tgz` archive: -+ --- -.Example command to create a `tgz` archive -[source,bash] ----- -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 -[source,bash] ----- -npm pack --json | head -n 10 ----- --- - -. Host the archive on a web server accessible to your {product-very-short} instance, and reference its URL in the `dynamic-plugin-config.yaml` file as follows: -+ --- -.Example `dynamic-plugin-config.yaml` file -[source,yaml] ----- -plugins: - - package: https://example.com/backstage-plugin-myplugin-1.0.0.tgz - integrity: sha512- ----- --- -. Run the following command to package the plugins: -+ --- -.Example command to package a dynamic plugin -[source,bash] ----- -npm pack --pack-destination ~/test/dynamic-plugins-root/ ----- - -[TIP] -==== -To create a plugin registry using HTTP server on {ocp-short}, run the following commands: - -.Example commands to build and deploy an HTTP server in {ocp-short} -[source,bash] ----- -oc project rhdh -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 ----- -==== --- - -. Configure your {product-very-short} to use plugins from the HTTP server by editing the `dynamic-plugin-config.yaml` file: -+ --- -.Example configuration to use packaged plugins in {product-very-short} -[source,yaml] ----- -plugins: - - package: http://plugin-registry:8080/backstage-plugin-myplugin-1.9.6.tgz ----- --- - -[#create-js-package] -== Creating a JavaScript package with dynamic packages - -[WARNING] -==== -The derived dynamic plugin JavaScript packages must not be published to the public NPM registry. If you must publish to the NPM registry, use a private registry. -==== - -.Prerequisites -* You have exported a third-party dynamic plugin package. For more information, see xref:proc-export-third-party-plugins-rhdh_{context}[]. - -.Procedure -. Navigate to the `dist-dynamic` directory. -. Run the following command to publish the package to your private NPM registry: -+ --- -.Example command to publish a plugin package to an NPM registry -[source,bash] ----- -npm publish --registry ----- - -[TIP] -==== -You can add the following to your `package.json` file before running the `export` command: - -.Example `package.json` file -[source,json] ----- -{ - "publishConfig": { - "registry": "" - } -} ----- - -If you modify the `publishConfig` after exporting the dynamic plugin, re-run the `export-dynamic-plugin` command to ensure the correct configuration is included. -==== --- - diff --git a/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc b/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc index 8444d74e3f..7121fb2fac 100644 --- a/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc +++ b/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc @@ -1,7 +1,7 @@ [id="ref-example-third-party-plugin-installation_{context}"] = Example of installing a third-party plugin in {product} -This section provides step-by-step instructions for integrating the link:https://github.com/backstage/community-plugins/tree/main/workspaces/todo/plugins[Todo plugin] into your {product-short}. +This section describes the process for integrating the link:https://github.com/backstage/community-plugins/tree/main/workspaces/todo/plugins[Todo plugin] into your {product-short}. . *Obtain the third-party plugin source code*: Clone the plugins repository and navigate to the link:https://github.com/backstage/community-plugins/tree/main/workspaces/todo/plugins[Todo plugin] directory: + @@ -18,14 +18,14 @@ $ yarn install . *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 a backend plugin +.Export the backend plugin [source,bash] ---- $ cd todo-backend $ npx @janus-idp/cli@latest package export-dynamic-plugin ---- -.Output of exporting a backend plugin commands +.Output of exporting the backend plugin commands [source,bash] ---- Building main package @@ -50,14 +50,14 @@ Saving self-contained config schema in /Users/user/Code/community-plugins/worksp 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 a front-end plugin +.Export the front-end plugin [source,bash] ---- $ cd ../todo $ npx @janus-idp/cli@latest package export-dynamic-plugin ---- -.Output of exporting a front-end plugin commands +.Output of exporting the front-end plugin commands [source,bash] ---- No scalprum config. Using default dynamic UI configuration: diff --git a/titles/plugins-rhdh-install/master.adoc b/titles/plugins-rhdh-install/master.adoc index 9b2ba0ca02..8994501326 100644 --- a/titles/plugins-rhdh-install/master.adoc +++ b/titles/plugins-rhdh-install/master.adoc @@ -12,7 +12,7 @@ include::artifacts/attributes.adoc[] include::assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc[leveloffset=+1] //third-party plugins -include::assemblies/dynamic-plugins/assembly-third-party-plugins-installation.adoc[leveloffset=+1] +include::assemblies/dynamic-plugins/assembly-third-party-plugins.adoc[leveloffset=+1] // Viewing installed plugins include::modules/dynamic-plugins/proc-viewing-installed-plugins.adoc[leveloffset=+1] From 3b37d791e48d2d7f0062480d92b49f81c4bc8621 Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Wed, 11 Dec 2024 15:17:43 +0530 Subject: [PATCH 07/10] review suggestions incorporated --- .../assembly-install-third-party-plugins-rhdh.adoc | 2 +- modules/dynamic-plugins/proc-create-plugin-js-package.adoc | 2 +- modules/dynamic-plugins/proc-load-plugin-oci-image.adoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc b/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc index 11423d617c..45c62d2e5f 100644 --- a/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc +++ b/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc @@ -8,7 +8,7 @@ The location of the `dynamic-plugin-config.yaml` file depends on the deployment Plugins are defined in the `plugins` array within the `dynamic-plugin-config.yaml` file. Each plugin is represented as an object with the following properties: -* `package`: The plugin's package definition, which can be an OCI image, a TGZ file, a JavaScript package, or a directory path +* `package`: The plugin's package definition, which can be an OCI image, a TGZ file, a JavaScript package, or a directory path. * `disabled`: A boolean value indicating whether the plugin is enabled or disabled. * `integrity`: The integrity hash of the package, required for TGZ file and JavaScript packages. * `pluginConfig`: The plugin's configuration. For backend plugins, this is optional; for frontend plugins, it is required. The `pluginConfig` is a fragment of the `app-config.yaml` file, and any added properties are merged with the {product-very-short} `app-config.yaml` file. diff --git a/modules/dynamic-plugins/proc-create-plugin-js-package.adoc b/modules/dynamic-plugins/proc-create-plugin-js-package.adoc index 9f0e882ab9..1a6bbd6c8b 100644 --- a/modules/dynamic-plugins/proc-create-plugin-js-package.adoc +++ b/modules/dynamic-plugins/proc-create-plugin-js-package.adoc @@ -34,6 +34,6 @@ You can add the following to your `package.json` file before running the `export } ---- -If you modify the `publishConfig` after exporting the dynamic plugin, re-run the `export-dynamic-plugin` command to ensure the correct configuration is included. +If you modify `publishConfig` after exporting the dynamic plugin, re-run the `export-dynamic-plugin` command to ensure the correct configuration is included. ==== -- \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-load-plugin-oci-image.adoc b/modules/dynamic-plugins/proc-load-plugin-oci-image.adoc index 4045d86f58..0fb9aa17bb 100644 --- a/modules/dynamic-plugins/proc-load-plugin-oci-image.adoc +++ b/modules/dynamic-plugins/proc-load-plugin-oci-image.adoc @@ -23,7 +23,7 @@ plugins: . 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`. -. To perform an integrity check, use the image digest in place of the tag in `dynamic-plugins.yaml` file as follows: +. 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 From 01a80c1004117dcd4e08ff3660556172d5375e41 Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Thu, 12 Dec 2024 19:16:31 +0530 Subject: [PATCH 08/10] review suggestions incorporated --- .../assembly-install-third-party-plugins-rhdh.adoc | 4 ++-- ...y-package-publish-third-party-dynamic-plugin.adoc | 2 +- .../assembly-third-party-plugins.adoc | 2 +- .../proc-export-third-party-plugins-rhdh.adoc | 12 +++++++----- 4 files changed, 11 insertions(+), 9 deletions(-) diff --git a/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc b/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc index 45c62d2e5f..06906e30d4 100644 --- a/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc +++ b/assemblies/dynamic-plugins/assembly-install-third-party-plugins-rhdh.adoc @@ -4,7 +4,7 @@ You can install a third-party plugins in {product} without rebuilding the {product-very-short} application. -The location of the `dynamic-plugin-config.yaml` file depends on the deployment method. For more details, refer to xref:proc-config-dynamic-plugins-rhdh-operator_rhdh-installing-rhdh-plugins[] and xref:con-install-dynamic-plugin-helm_rhdh-installing-rhdh-plugins[]. +The location of the `dynamic-plugin-config.yaml` file depends on the deployment method. For more details, refer to xref:proc-config-dynamic-plugins-rhdh-operator_rhdh-installing-rhdh-plugins[Installing dynamic plugins with the {product} Operator] and xref:con-install-dynamic-plugin-helm_rhdh-installing-rhdh-plugins[Installing dynamic plugins using the Helm chart]. Plugins are defined in the `plugins` array within the `dynamic-plugin-config.yaml` file. Each plugin is represented as an object with the following properties: @@ -15,7 +15,7 @@ Plugins are defined in the `plugins` array within the `dynamic-plugin-config.yam [NOTE] ==== -You can also load dynamic plugins from a plain directory, though this is intended for development or testing purposes and is not recommended for production, except for plugins included in the {product-very-short} container image. +You can also load dynamic plugins from another directory, though this is intended for development or testing purposes and is not recommended for production, except for plugins included in the {product-very-short} container image. ==== //OCI image diff --git a/assemblies/dynamic-plugins/assembly-package-publish-third-party-dynamic-plugin.adoc b/assemblies/dynamic-plugins/assembly-package-publish-third-party-dynamic-plugin.adoc index 699b67bb8c..b61169a238 100644 --- a/assemblies/dynamic-plugins/assembly-package-publish-third-party-dynamic-plugin.adoc +++ b/assemblies/dynamic-plugins/assembly-package-publish-third-party-dynamic-plugin.adoc @@ -7,7 +7,7 @@ After xref:proc-export-third-party-plugins-rhdh_assembly-third-party-plugins[exp * Open Container Initiative (OCI) image (recommended) * TGZ file * JavaScript package - ++ [IMPORTANT] ==== Exported dynamic plugin packages must only be published to private NPM registries. diff --git a/assemblies/dynamic-plugins/assembly-third-party-plugins.adoc b/assemblies/dynamic-plugins/assembly-third-party-plugins.adoc index ef5c1c4f05..4184bd6235 100644 --- a/assemblies/dynamic-plugins/assembly-third-party-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-third-party-plugins.adoc @@ -2,7 +2,7 @@ = Third-party plugins in {product} :context: assembly-third-party-plugins -You can integrate third-party dynamic plugins in {product}. This flexibility allows you to enhance the platform functionality without modifying its source code and rebuilding. To add third-party dynamic plugins, you can export them as derived package. +You can integrate third-party dynamic plugins into {product} to enhance its functionality without modifying its source code or rebuilding it. To add these plugins, export them as derived packages. While exporting the plugin package, you must ensure that dependencies are correctly bundled or marked as shared, depending on their relationship to the {product-short} environment. diff --git a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc index cce204fbef..80d9763629 100644 --- a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc +++ b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc @@ -6,9 +6,9 @@ To use plugins in {product}, you can export plugins as derived dynamic plugin pa Backend plugins:: + -- -To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with the new backend system. Additionally, these plugins must be rebuilt using a dedicated CLI command. +To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with the backend system. Additionally, these plugins must be rebuilt using a dedicated CLI command. -The new backend system entry point (created using `createBackendPlugin()` or `createBackendModule()`) must be exported as the default export from either the main package or an `alpha` package (if the plugin instance support is still provided using `alpha` APIs). This doesn't add any additional requirement on top of the standard plugin development guidelines of the plugin instance. +The backend system entry point (created using `createBackendPlugin()` or `createBackendModule()`) must be exported as the default export from either the main package or an `alpha` package (if the plugin instance support is still provided using `alpha` APIs). This doesn't add any additional requirement on top of the standard plugin development guidelines of the plugin instance. The dynamic export mechanism identifies private dependencies and sets the `bundleDependencies` field in the `package.json` file. This export mechanism ensures that the dynamic plugin package is published as a self-contained package, with its private dependencies bundled in a private `node_modules` folder. @@ -29,7 +29,7 @@ The following is an example of exporting a dynamic plugin with shared and embedd .Example dynamic plugin export with shared and embedded packages [source,bash] ---- -npx @janus-idp/cli@latest export-dynamic-plugin --shared-package '!/@backstage/plugin-notifications/'<1> --embed-package @backstage/plugin-notifications-backend <2> +npx @janus-idp/cli@latest export-dynamic-plugin --shared-package '!/@backstage/plugin-notifications/' <1> --embed-package @backstage/plugin-notifications-backend <2> ---- <1> `@backstage/plugin-notifications` package is treated as a private dependency and is bundled in the dynamic plugin package, despite being in the `@backstage` scope. @@ -104,8 +104,9 @@ export const DynamicEntityTechdocsContent = { * The third-party plugin is compatible with your {product} version. For more information, see link:https://github.com/janus-idp/backstage-showcase/blob/main/docs/dynamic-plugins/versions.md[Version compatibility matrix]. .Procedure -Use the `package export-dynamic-plugin` command from the `@janus-idp/cli` package to export the plugin: - +* Use the `package export-dynamic-plugin` command from the `@janus-idp/cli` package to export the plugin: ++ +-- .Example command to export a third-party plugin [source,bash] ---- @@ -120,5 +121,6 @@ The resulting derived package will be located in the `dist-dynamic` subfolder. T ==== The derived dynamic plugin JavaScript packages must not be published to the public NPM registry. For more appropriate packaging options, see xref:assembly-package-publish-third-party-dynamic-plugin[]. If you must publish to the NPM registry, use a private registry. ==== +-- From 076cd9ef245eb3b6bbe41fcd1c0d83ff77b1a3ed Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Thu, 12 Dec 2024 20:42:35 +0530 Subject: [PATCH 09/10] review suggestions incorporated --- .../proc-export-third-party-plugins-rhdh.adoc | 50 +++++++++---------- 1 file changed, 24 insertions(+), 26 deletions(-) diff --git a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc index 80d9763629..5cf7701ffa 100644 --- a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc +++ b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc @@ -3,17 +3,23 @@ To use plugins in {product}, you can export plugins as derived dynamic plugin packages. These packages contain the plugin code and dependencies, ready for dynamic plugin integration into {product-short}. -Backend plugins:: +.Prerequisites +* The `@janus-idp/cli` package is installed. Use the latest version (`@latest` tag) for compatibility with the most recent features and fixes. +* Node.js and NPM is installed and configured. +* The third-party plugin is compatible with your {product} version. For more information, see link:https://github.com/janus-idp/backstage-showcase/blob/main/docs/dynamic-plugins/versions.md[Version compatibility matrix]. +* The third-party plugin must have a valid `package.json` file in its root directory, containing all required metadata and dependencies. + -- -To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with the backend system. Additionally, these plugins must be rebuilt using a dedicated CLI command. - -The backend system entry point (created using `createBackendPlugin()` or `createBackendModule()`) must be exported as the default export from either the main package or an `alpha` package (if the plugin instance support is still provided using `alpha` APIs). This doesn't add any additional requirement on top of the standard plugin development guidelines of the plugin instance. - +Backend plugins:: ++ +To ensure compatibility with the dynamic plugin support and enable their use as dynamic plugins, existing backend plugins must be compatible with the new Backstage backend system. Additionally, these plugins must be rebuilt using a dedicated CLI command. ++ +The new Backstage backend system entry point (created using `createBackendPlugin()` or `createBackendModule()`) must be exported as the default export from either the main package or an `alpha` package (if the plugin instance support is still provided using `alpha` APIs). This doesn't add any additional requirement on top of the standard plugin development guidelines of the plugin instance. ++ The dynamic export mechanism identifies private dependencies and sets the `bundleDependencies` field in the `package.json` file. This export mechanism ensures that the dynamic plugin package is published as a self-contained package, with its private dependencies bundled in a private `node_modules` folder. - ++ Certain plugin dependencies require specific handling in the derived packages, such as: - ++ * *Shared dependencies* are provided by the {product-very-short} application and listed as `peerDependencies` in `package.json` file, not bundled in the dynamic plugin package. For example, by default, all `@backstage` scoped packages are shared. + You can use the `--shared-package` flag to specify shared dependencies, that are expected to be provided by {product} application and not bundled in the dynamic plugin package. @@ -23,32 +29,30 @@ To treat a `@backstage` package as private, use the negation prefix (`!`). For e * *Embedded dependencies* are bundled into the dynamic plugin package with their dependencies hoisted to the top level. By default, packages with `-node` or `-common` suffixes are embedded. + You can use the `--embed-package` flag to specify additional embedded packages. For example, packages from the same workspace that do not follow the default naming convention. - ++ The following is an example of exporting a dynamic plugin with shared and embedded packages: - ++ .Example dynamic plugin export with shared and embedded packages [source,bash] ---- npx @janus-idp/cli@latest export-dynamic-plugin --shared-package '!/@backstage/plugin-notifications/' <1> --embed-package @backstage/plugin-notifications-backend <2> ---- - ++ <1> `@backstage/plugin-notifications` package is treated as a private dependency and is bundled in the dynamic plugin package, despite being in the `@backstage` scope. <2> `@backstage/plugin-notifications-backend` package is marked as an embedded dependency and is bundled in the dynamic plugin package. --- Front-end plugins:: + --- Front-end plugins can use `scalprum` for configuration, which the CLI can generate automatically during the export process. The generated default configuration is logged when running the following command: - ++ .Example command to log the default configuration [source,bash] ---- npx @janus-idp/cli@latest export-dynamic ---- - ++ The following is an example of default `scalprum` configuration: - ++ .Default `scalprum` configuration [source,json] ---- @@ -59,9 +63,9 @@ The following is an example of default `scalprum` configuration: } } ---- - ++ You can add a `scalprum` section to the `package.json` file. For example: - ++ .Example `scalprum` customization [source,json] ---- @@ -74,11 +78,11 @@ You can add a `scalprum` section to the `package.json` file. For example: } } ---- - ++ Dynamic plugins might need adjustments for {product-short} needs, such as static JSX for mountpoints or dynamic routes. These changes are optional but might be incompatible with static plugins. - ++ To include static JSX, define an additional export and use it as the dynamic plugin's `importName`. For example: - ++ .Example static and dynamic plugin export [source,tsx] ---- @@ -97,12 +101,6 @@ export const DynamicEntityTechdocsContent = { ---- -- -.Prerequisites -* The `@janus-idp/cli` package is installed. Use the latest version (`@latest` tag) for compatibility with the most recent features and fixes. -* The third-party plugin must have a valid package.json file in its root directory, containing all required metadata and dependencies. -* Node.js and NPM is installed and configured. -* The third-party plugin is compatible with your {product} version. For more information, see link:https://github.com/janus-idp/backstage-showcase/blob/main/docs/dynamic-plugins/versions.md[Version compatibility matrix]. - .Procedure * Use the `package export-dynamic-plugin` command from the `@janus-idp/cli` package to export the plugin: + From dc1fcf08061d8a51131ea9001fabadfd98458ae9 Mon Sep 17 00:00:00 2001 From: Heena Manwani Date: Fri, 13 Dec 2024 20:02:05 +0530 Subject: [PATCH 10/10] review suggestions incorporated --- .../proc-create-plugin-js-package.adoc | 2 +- .../proc-create-plugin-oci-image.adoc | 6 +++--- .../proc-create-plugin-tgz-file.adoc | 8 ++++---- .../proc-export-third-party-plugins-rhdh.adoc | 6 +++--- .../proc-load-plugin-js-package.adoc | 2 +- ...xample-third-party-plugin-installation.adoc | 18 +++++++++--------- 6 files changed, 21 insertions(+), 21 deletions(-) diff --git a/modules/dynamic-plugins/proc-create-plugin-js-package.adoc b/modules/dynamic-plugins/proc-create-plugin-js-package.adoc index 1a6bbd6c8b..a88fac0c35 100644 --- a/modules/dynamic-plugins/proc-create-plugin-js-package.adoc +++ b/modules/dynamic-plugins/proc-create-plugin-js-package.adoc @@ -15,7 +15,7 @@ The derived dynamic plugin JavaScript packages must not be published to the publ + -- .Example command to publish a plugin package to an NPM registry -[source,bash] +[source,terminal] ---- npm publish --registry ---- diff --git a/modules/dynamic-plugins/proc-create-plugin-oci-image.adoc b/modules/dynamic-plugins/proc-create-plugin-oci-image.adoc index a332d012a6..e7acecaaf6 100644 --- a/modules/dynamic-plugins/proc-create-plugin-oci-image.adoc +++ b/modules/dynamic-plugins/proc-create-plugin-oci-image.adoc @@ -11,7 +11,7 @@ + -- .Example command to package an exported third-party plugin -[source,bash] +[source,terminal] ---- npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/example/image:v0.0.1 ---- @@ -22,13 +22,13 @@ In the previous command, the `--tag` argument specifies the image name and tag. + -- .Example command to push an image to a registry using podman -[source,bash] +[source,terminal] ---- podman push quay.io/example/image:v0.0.1 ---- .Example command to push an image to a registry using docker -[source,bash] +[source,terminal] ---- docker push quay.io/example/image:v0.0.1 ---- diff --git a/modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc b/modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc index 199d710119..1c42f6e488 100644 --- a/modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc +++ b/modules/dynamic-plugins/proc-create-plugin-tgz-file.adoc @@ -10,14 +10,14 @@ + -- .Example command to create a `tgz` archive -[source,bash] +[source,terminal] ---- 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 -[source,bash] +[source,terminal] ---- npm pack --json | head -n 10 ---- @@ -38,7 +38,7 @@ plugins: + -- .Example command to package a dynamic plugin -[source,bash] +[source,terminal] ---- npm pack --pack-destination ~/test/dynamic-plugins-root/ ---- @@ -48,7 +48,7 @@ npm pack --pack-destination ~/test/dynamic-plugins-root/ To create a plugin registry using HTTP server on {ocp-short}, run the following commands: .Example commands to build and deploy an HTTP server in {ocp-short} -[source,bash] +[source,terminal] ---- oc project rhdh oc new-build httpd --name=plugin-registry --binary diff --git a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc index 5cf7701ffa..d217271d66 100644 --- a/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc +++ b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc @@ -33,7 +33,7 @@ You can use the `--embed-package` flag to specify additional embedded packages. The following is an example of exporting a dynamic plugin with shared and embedded packages: + .Example dynamic plugin export with shared and embedded packages -[source,bash] +[source,terminal] ---- npx @janus-idp/cli@latest export-dynamic-plugin --shared-package '!/@backstage/plugin-notifications/' <1> --embed-package @backstage/plugin-notifications-backend <2> ---- @@ -46,7 +46,7 @@ Front-end plugins:: Front-end plugins can use `scalprum` for configuration, which the CLI can generate automatically during the export process. The generated default configuration is logged when running the following command: + .Example command to log the default configuration -[source,bash] +[source,terminal] ---- npx @janus-idp/cli@latest export-dynamic ---- @@ -106,7 +106,7 @@ export const DynamicEntityTechdocsContent = { + -- .Example command to export a third-party plugin -[source,bash] +[source,terminal] ---- npx @janus-idp/cli@latest package export-dynamic-plugin ---- diff --git a/modules/dynamic-plugins/proc-load-plugin-js-package.adoc b/modules/dynamic-plugins/proc-load-plugin-js-package.adoc index fe8cbafa09..9412336da8 100644 --- a/modules/dynamic-plugins/proc-load-plugin-js-package.adoc +++ b/modules/dynamic-plugins/proc-load-plugin-js-package.adoc @@ -10,7 +10,7 @@ For more information about packaging a third-party plugin, see xref:assembly-pac . Run the following command to obtain the integrity hash from the NPM registry: + -- -[source,bash] +[source,terminal] ---- npm view --registry @ dist.integrity ---- diff --git a/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc b/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc index 7121fb2fac..8d97498464 100644 --- a/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc +++ b/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc @@ -7,7 +7,7 @@ This section describes the process for integrating the link:https://github.com/b + -- .Obtain the third-party plugin source code -[source,bash] +[source,terminal] ---- $ git clone https://github.com/backstage/community-plugins $ cd community-plugins/workspaces/todo @@ -19,14 +19,14 @@ $ yarn install + -- .Export the backend plugin -[source,bash] +[source,terminal] ---- $ cd todo-backend $ npx @janus-idp/cli@latest package export-dynamic-plugin ---- .Output of exporting the backend plugin commands -[source,bash] +[source,terminal] ---- Building main package executing yarn build ✔ @@ -51,14 +51,14 @@ Saving self-contained config schema in /Users/user/Code/community-plugins/worksp 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 -[source,bash] +[source,terminal] ---- $ cd ../todo $ npx @janus-idp/cli@latest package export-dynamic-plugin ---- .Output of exporting the front-end plugin commands -[source,bash] +[source,terminal] ---- No scalprum config. Using default dynamic UI configuration: { @@ -84,14 +84,14 @@ Saving self-contained config schema in /Users/user/Code/community-plugins/worksp + -- .Build an OCI image -[source,bash] +[source,terminal] ---- $ 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 -[source,bash] +[source,terminal] ---- executing podman --version ✔ Using existing 'dist-dynamic' directory at plugins/todo @@ -120,13 +120,13 @@ plugins: ---- .Push the OCI image to a container registry: -[source,bash] +[source,terminal] ---- $ podman push quay.io/user/backstage-community-plugin-todo:v0.1.1 ---- .Output of pushing the OCI image command -[source,bash] +[source,terminal] ---- Getting image source signatures Copying blob sha256:86a372c456ae6a7a305cd464d194aaf03660932efd53691998ab3403f87cacb5