From b1f6b686371f81c975c136e9580c1dc7dfa13334 Mon Sep 17 00:00:00 2001 From: cmoulliard Date: Wed, 3 Apr 2024 09:36:02 +0200 Subject: [PATCH 1/3] Adding a Table of contents to the dynamic-plugins.md file Signed-off-by: cmoulliard --- showcase-docs/dynamic-plugins.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/showcase-docs/dynamic-plugins.md b/showcase-docs/dynamic-plugins.md index 160f8a098..dab0d87a7 100644 --- a/showcase-docs/dynamic-plugins.md +++ b/showcase-docs/dynamic-plugins.md @@ -1,5 +1,36 @@ # Dynamic Plugins support +# Table of Contents + +- [Overview](#overview) +- [How it works](#how-it-works) +- [Preparing dynamic plugins for the showcase](#preparing-dynamic-plugins-for-the-showcase) + - [Backend plugins](#backend-plugins) + - [Required code changes](#required-code-changes) + - [Note about the new backend system support](#note-about-the-new-backend-system-support) + - [Exporting the backend plugin as a dynamic plugin package](#exporting-the-backend-plugin-as-a-dynamic-plugin-package) + - [Publishing the dynamic backend plugin package to an NPM registry](#publishing-the-dynamic-backend-plugin-package-to-an-npm-registry) + - [About embedding dependencies in the plugin package](#about-embedding-dependencies-in-the-plugin-package) + - [Wrapping a third-party backend plugin to add dynamic plugin support](#wrapping-a-third-party-backend-plugin-to-add-dynamic-plugin-support) + - [Frontend plugins](#frontend-plugins) + - [Required code changes](#required-code-changes-1) + - [Exporting the plugin as a dynamic plugin package](#exporting-the-plugin-as-a-dynamic-plugin-package) + - [Wrapping a third-party frontend plugin to add dynamic plugin support](#wrapping-a-third-party-frontend-plugin-to-add-dynamic-plugin-support) +- [Installing a dynamic plugin package in the showcase](#installing-a-dynamic-plugin-package-in-the-showcase) + - [Local configuration](#local-configuration) + - [Helm deployment](#helm-deployment) + - [Dynamic plugins included in the Showcase container image](#dynamic-plugins-included-in-the-showcase-container-image) + - [Example of external dynamic backend plugins](#example-of-external-dynamic-backend-plugins) + - [Using a custom NPM registry](#using-a-custom-npm-registry) + - [Air Gapped Environment](#air-gapped-environment) +- [Plugin configuration](#plugin-configuration) + - [Frontend layout configuration](#frontend-layout-configuration) + - [Extend internal library of available icons](#extend-internal-library-of-available-icons) + - [Dynamic routes](#dynamic-routes) + - [Bind to existing plugins](#bind-to-existing-plugins) + - [Using mount points](#using-mount-points) + - [Provide additional Utility APIs](#provide-additional-utility-apis) + ## Overview This document describes how to enable the dynamic plugins feature in the Janus Backstage showcase application. From e45d965d4dc7896511609dd72794e72b26d5fb0f Mon Sep 17 00:00:00 2001 From: cmoulliard Date: Wed, 3 Apr 2024 10:13:14 +0200 Subject: [PATCH 2/3] Add the Quarkus tab. Enhance the documentation Signed-off-by: cmoulliard --- .../components/catalog/EntityPage/index.tsx | 6 ++ showcase-docs/dynamic-plugins.md | 92 +++++++++++++------ 2 files changed, 72 insertions(+), 26 deletions(-) diff --git a/packages/app/src/components/catalog/EntityPage/index.tsx b/packages/app/src/components/catalog/EntityPage/index.tsx index d9b4d3dcd..4682b0f26 100644 --- a/packages/app/src/components/catalog/EntityPage/index.tsx +++ b/packages/app/src/components/catalog/EntityPage/index.tsx @@ -293,6 +293,12 @@ export const entityPage = ( ), })} + {tab({ + path: '/quarkus', + title: 'Quarkus', + mountPoint: 'entity.page.quarkus', + })} + {tab({ path: '/topology', title: 'Topology', diff --git a/showcase-docs/dynamic-plugins.md b/showcase-docs/dynamic-plugins.md index dab0d87a7..5bfdccf05 100644 --- a/showcase-docs/dynamic-plugins.md +++ b/showcase-docs/dynamic-plugins.md @@ -301,14 +301,18 @@ In order to add dynamic plugin support to a third-party front plugin, without to - Create a `dynamic-plugins-root` folder at the root of the showcase application repository. -- In the `app-config.yaml` file, add the following entry: +- To use the `dynamic` plugins packaged within this project, generate and copy them to the `dynamic-plugins-root` using the following commands: - ```yaml - dynamicPlugins: - rootDirectory: dynamic-plugins-root + ```bash + yarn tsc + yarn build + yarn export-dynamic + yarn copy-dynamic-plugins ../dynamic-plugins-root ``` -- Copy the dynamic plugin package to the `dynamic-plugins-root` folder with the following commands: + **Note**: Review the list of the dynamic plugins copied and keep the ones you need or use all of them ! + +- Copy your dynamic plugin package(s) to be tested/developed to the `dynamic-plugins-root` folder using the following commands: ```bash pkg= @@ -319,10 +323,45 @@ In order to add dynamic plugin support to a third-party front plugin, without to It will create a sub-folder named after the package name, and containing the dynamic plugin package. +- In the `app-config.local.yaml` file, add the following entry at the end: + + ```yaml + dynamicPlugins: + rootDirectory: dynamic-plugins-root + ``` + +- Append next to this file the `frontend` [configurations](..%2Fdynamic-plugins.default.yaml) as they are not loaded automatically when backstage runs locally vs on ocp (as packaged within the backstage-showcase image): + + ```yaml + dynamicPlugins: + rootDirectory: qshift-dynamic-plugins-root + frontend: + # Your plugin config ! + + # Kubernetes, Topology, Tekton, etc config + + # RBAC page in the app-provided Administration page + janus-idp.backstage-plugin-rbac: + dynamicRoutes: + - path: /admin/rbac + module: RbacPlugin + importName: RbacPage + mountPoints: + - mountPoint: admin.page.rbac/cards + module: RbacPlugin + importName: RbacPage + config: + layout: + gridColumn: '1 / -1' + width: 100vw + props: + useHeader: false + ``` + - Start the showcase application. During the initialization step it should have a log entry similar to the following: ```bash - backstage info loaded dynamic backend plugin '@scope/some-plugin-dynamic' from 'file:///showacase-root/dynamic-plugins-root/scope-some-plugin-dynamic-0.0.1' + backstage info loaded dynamic backend plugin '@scope/some-plugin-dynamic' from 'file:///showcase-root/dynamic-plugins-root/scope-some-plugin-dynamic-0.0.1' ``` ### Helm deployment @@ -648,26 +687,27 @@ Mount points are defined identifiers available across the applications. These po The following mount points are available: -| Mount point | Description | Visible even when no plugins are enabled | -| ---------------------------- | ----------------------------------- | -------------------------------------------------------------- | -| `entity.page.overview` | Catalog entity overview page | YES for all entities | -| `entity.page.topology` | Catalog entity "Topology" tab | NO | -| `entity.page.issues` | Catalog entity "Issues" tab | NO | -| `entity.page.pull-requests` | Catalog entity "Pull Requests" tab | NO | -| `entity.page.ci` | Catalog entity "CI" tab | NO | -| `entity.page.cd` | Catalog entity "CD" tab | NO | -| `entity.page.kubernetes` | Catalog entity "Kubernetes" tab | NO | -| `entity.page.image-registry` | Catalog entity "Image Registry" tab | NO | -| `entity.page.monitoring` | Catalog entity "Monitoring" tab | NO | -| `entity.page.lighthouse` | Catalog entity "Lighthouse" tab | NO | -| `entity.page.api` | Catalog entity "API" tab | YES for entity of `kind: Component` and `spec.type: 'service'` | -| `entity.page.dependencies` | Catalog entity "Dependencies" tab | YES for entity of `kind: Component` | -| `entity.page.docs` | Catalog entity "Documentation" tab | YES for entity that satisfies `isTechDocsAvailable` | -| `entity.page.definition` | Catalog entity "Definitions" tab | YES for entity of `kind: Api` | -| `entity.page.diagram` | Catalog entity "Diagram" tab | YES for entity of `kind: System` | -| `search.page.types` | Search result type | YES, default catalog search type is available | -| `search.page.filters` | Search filters | YES, default catalog kind and lifecycle filters are visible | -| `search.page.results` | Search results content | YES, default catalog search is present | +| Mount point | Description | Visible even when no plugins are enabled | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| `entity.page.overview` | Catalog entity overview page | YES for all entities | +| `entity.page.topology` | Catalog entity "Topology" tab | NO | +| `entity.page.quarkus` | Catalog entity "[Quarkus](https://github.com/q-shift/backstage-plugins/?tab=readme-ov-file#quarkus-console)" tab | NO | +| `entity.page.issues` | Catalog entity "Issues" tab | NO | +| `entity.page.pull-requests` | Catalog entity "Pull Requests" tab | NO | +| `entity.page.ci` | Catalog entity "CI" tab | NO | +| `entity.page.cd` | Catalog entity "CD" tab | NO | +| `entity.page.kubernetes` | Catalog entity "Kubernetes" tab | NO | +| `entity.page.image-registry` | Catalog entity "Image Registry" tab | NO | +| `entity.page.monitoring` | Catalog entity "Monitoring" tab | NO | +| `entity.page.lighthouse` | Catalog entity "Lighthouse" tab | NO | +| `entity.page.api` | Catalog entity "API" tab | YES for entity of `kind: Component` and `spec.type: 'service'` | +| `entity.page.dependencies` | Catalog entity "Dependencies" tab | YES for entity of `kind: Component` | +| `entity.page.docs` | Catalog entity "Documentation" tab | YES for entity that satisfies `isTechDocsAvailable` | +| `entity.page.definition` | Catalog entity "Definitions" tab | YES for entity of `kind: Api` | +| `entity.page.diagram` | Catalog entity "Diagram" tab | YES for entity of `kind: System` | +| `search.page.types` | Search result type | YES, default catalog search type is available | +| `search.page.filters` | Search filters | YES, default catalog kind and lifecycle filters are visible | +| `search.page.results` | Search results content | YES, default catalog search is present | Note: Mount points within Catalog aka `entity.page.*` are rendered as tabs. They become visible only if at least one plugin contributes to them or they can render static content (see column 3 in previous table). From c0a6adbd686ed0a95784b4e03de7f6a424a9251f Mon Sep 17 00:00:00 2001 From: cmoulliard Date: Wed, 3 Apr 2024 11:27:25 +0200 Subject: [PATCH 3/3] Removing the TOC as github viewer proposes one by default Signed-off-by: cmoulliard --- showcase-docs/dynamic-plugins.md | 31 ------------------------------- 1 file changed, 31 deletions(-) diff --git a/showcase-docs/dynamic-plugins.md b/showcase-docs/dynamic-plugins.md index 5bfdccf05..827ab99a8 100644 --- a/showcase-docs/dynamic-plugins.md +++ b/showcase-docs/dynamic-plugins.md @@ -1,36 +1,5 @@ # Dynamic Plugins support -# Table of Contents - -- [Overview](#overview) -- [How it works](#how-it-works) -- [Preparing dynamic plugins for the showcase](#preparing-dynamic-plugins-for-the-showcase) - - [Backend plugins](#backend-plugins) - - [Required code changes](#required-code-changes) - - [Note about the new backend system support](#note-about-the-new-backend-system-support) - - [Exporting the backend plugin as a dynamic plugin package](#exporting-the-backend-plugin-as-a-dynamic-plugin-package) - - [Publishing the dynamic backend plugin package to an NPM registry](#publishing-the-dynamic-backend-plugin-package-to-an-npm-registry) - - [About embedding dependencies in the plugin package](#about-embedding-dependencies-in-the-plugin-package) - - [Wrapping a third-party backend plugin to add dynamic plugin support](#wrapping-a-third-party-backend-plugin-to-add-dynamic-plugin-support) - - [Frontend plugins](#frontend-plugins) - - [Required code changes](#required-code-changes-1) - - [Exporting the plugin as a dynamic plugin package](#exporting-the-plugin-as-a-dynamic-plugin-package) - - [Wrapping a third-party frontend plugin to add dynamic plugin support](#wrapping-a-third-party-frontend-plugin-to-add-dynamic-plugin-support) -- [Installing a dynamic plugin package in the showcase](#installing-a-dynamic-plugin-package-in-the-showcase) - - [Local configuration](#local-configuration) - - [Helm deployment](#helm-deployment) - - [Dynamic plugins included in the Showcase container image](#dynamic-plugins-included-in-the-showcase-container-image) - - [Example of external dynamic backend plugins](#example-of-external-dynamic-backend-plugins) - - [Using a custom NPM registry](#using-a-custom-npm-registry) - - [Air Gapped Environment](#air-gapped-environment) -- [Plugin configuration](#plugin-configuration) - - [Frontend layout configuration](#frontend-layout-configuration) - - [Extend internal library of available icons](#extend-internal-library-of-available-icons) - - [Dynamic routes](#dynamic-routes) - - [Bind to existing plugins](#bind-to-existing-plugins) - - [Using mount points](#using-mount-points) - - [Provide additional Utility APIs](#provide-additional-utility-apis) - ## Overview This document describes how to enable the dynamic plugins feature in the Janus Backstage showcase application.