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..06906e30d4 --- /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[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: + +* `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 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 +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-installing-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc index 70b58f271b..35e1ee5816 100644 --- a/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc @@ -1,25 +1,23 @@ [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. 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] //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] 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] -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-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..b61169a238 --- /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.adoc b/assemblies/dynamic-plugins/assembly-third-party-plugins.adoc new file mode 100644 index 0000000000..4184bd6235 --- /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 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. + +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..a88fac0c35 --- /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,terminal] +---- +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 `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..e7acecaaf6 --- /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,terminal] +---- +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,terminal] +---- +podman push quay.io/example/image:v0.0.1 +---- + +.Example command to push an image to a registry using docker +[source,terminal] +---- +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..1c42f6e488 --- /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,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,terminal] +---- +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,terminal] +---- +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,terminal] +---- +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 new file mode 100644 index 0000000000..d217271d66 --- /dev/null +++ b/modules/dynamic-plugins/proc-export-third-party-plugins-rhdh.adoc @@ -0,0 +1,124 @@ +[id="proc-export-third-party-plugins-rhdh_{context}"] += Exporting third-party plugins in {product} + +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}. + +.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. ++ +-- +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. ++ +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. 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,terminal] +---- +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,terminal] +---- +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: ( + + + + ), +}; +---- +-- + +.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,terminal] +---- +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: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-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-load-plugin-js-package.adoc b/modules/dynamic-plugins/proc-load-plugin-js-package.adoc new file mode 100644 index 0000000000..9412336da8 --- /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,terminal] +---- +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..0fb9aa17bb --- /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 the `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/ref-example-third-party-plugin-installation.adoc b/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc new file mode 100644 index 0000000000..8d97498464 --- /dev/null +++ b/modules/dynamic-plugins/ref-example-third-party-plugin-installation.adoc @@ -0,0 +1,160 @@ +[id="ref-example-third-party-plugin-installation_{context}"] += Example of installing a third-party plugin in {product} + +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: ++ +-- +.Obtain the third-party plugin source code +[source,terminal] +---- +$ 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: ++ +-- +.Export the backend plugin +[source,terminal] +---- +$ cd todo-backend +$ npx @janus-idp/cli@latest package export-dynamic-plugin +---- + +.Output of exporting the backend plugin commands +[source,terminal] +---- +Building main package + executing yarn build ✔ +Packing main package to dist-dynamic/package.json +Customizing main package in dist-dynamic/package.json for dynamic loading + moving @backstage/backend-common to peerDependencies + moving @backstage/backend-openapi-utils to peerDependencies + moving @backstage/backend-plugin-api to peerDependencies + moving @backstage/catalog-client to peerDependencies + moving @backstage/catalog-model to peerDependencies + moving @backstage/config to peerDependencies + moving @backstage/errors to peerDependencies + moving @backstage/integration to peerDependencies + moving @backstage/plugin-catalog-node to peerDependencies +Installing private dependencies of the main package + executing yarn install --no-immutable ✔ +Validating private dependencies +Validating plugin entry points +Saving self-contained config schema in /Users/user/Code/community-plugins/workspaces/todo/plugins/todo-backend/dist-dynamic/dist/configSchema.json +---- + +You can run the following commands to set default dynamic UI configurations, create front-end plugin assets, and to generate a configuration schema for a front-end plugin: + +.Export the front-end plugin +[source,terminal] +---- +$ cd ../todo +$ npx @janus-idp/cli@latest package export-dynamic-plugin +---- + +.Output of exporting the front-end plugin commands +[source,terminal] +---- +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: ++ +-- +.Build an OCI image +[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,terminal] +---- + 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,terminal] +---- +$ podman push quay.io/user/backstage-community-plugin-todo:v0.1.1 +---- + +.Output of pushing the OCI image command +[source,terminal] +---- +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: ++ +-- +.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 diff --git a/titles/plugins-rhdh-install/master.adoc b/titles/plugins-rhdh-install/master.adoc index c074fc579f..8994501326 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.adoc[leveloffset=+1] + +// Viewing installed plugins +include::modules/dynamic-plugins/proc-viewing-installed-plugins.adoc[leveloffset=+1]