review suggestions incorporated

Author: hmanwani-rh

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]
+

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]

assemblies/dynamic-plugins/assembly-third-party-plugins-installation.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]
+
+
+

assemblies/dynamic-plugins/assembly-third-party-plugins.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 <npm_registry_url>
+----
+
+[TIP]
+====
+You can add the following to your `package.json` file before running the `export` command:
+
+.Example `package.json` file
+[source,json]
+----
+{
+  "publishConfig": {
+    "registry": "<npm_registry_url>"
+  }
+}
+----
+
+If you modify the `publishConfig` after exporting the dynamic plugin, re-run the `export-dynamic-plugin` command to ensure the correct configuration is included.
+====
+--

modules/dynamic-plugins/proc-create-plugin-js-package.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.
+--

modules/dynamic-plugins/proc-create-plugin-oci-image.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-<hash>
+----
+--
+. 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
+----
+--

modules/dynamic-plugins/proc-create-plugin-tgz-file.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.
 ====