diff --git a/artifacts/rhdh-plugins-reference/quickstart/quickstart-plugin-admin.adoc b/artifacts/rhdh-plugins-reference/quickstart/quickstart-plugin-admin.adoc new file mode 100644 index 0000000000..8c47bc3aa9 --- /dev/null +++ b/artifacts/rhdh-plugins-reference/quickstart/quickstart-plugin-admin.adoc @@ -0,0 +1,55 @@ +[id="installing-configuring-quickstart-plugin"] += Installing and configuring the Quickstart plugin + +The Quickstart plugin provides a guided onboarding experience for new users of {product}. It displays a customizable drawer interface with interactive quickstart steps that help users get familiar with the platform. + +== Installation +The Quickstart plugin is pre-loaded in {product-short} with basic configuration properties, and enabled by default. To disable it, set the disabled property to `true` as follows: + +[source,yaml] +---- +global: + dynamic: + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-quickstart + disabled: true +---- + +== Configuration +Configure quickstart items in your `app-config.yaml`: + +[source,yaml] +---- +app: + quickstart: + - title: 'Welcome to Developer Hub' + description: 'Learn the basics of navigating the Developer Hub interface' + icon: 'home' + cta: + text: 'Get Started' + link: '/catalog' + - title: 'Create Your First Component' + description: 'Follow our guide to register your first software component' + icon: 'code' + cta: + text: 'Create Component' + link: '/catalog-import' + - title: 'Explore Templates' + description: 'Discover available software templates to bootstrap new projects' + icon: 'template' + cta: + text: 'Browse Templates' + link: '/create' +---- + +== Configuration Schema +Each quickstart item supports the following properties: + +* `title` (required): The display title for the quickstart step +* `description` (required): A brief description of what the step covers +* `icon` (optional): Icon identifier (supports Material UI icons) +* `cta` (optional): Call-to-action object with: +* `text`: Button text +* `link`: Target URL or route \ No newline at end of file diff --git a/artifacts/rhdh-plugins-reference/quickstart/quickstart-plugin-user.adoc b/artifacts/rhdh-plugins-reference/quickstart/quickstart-plugin-user.adoc new file mode 100644 index 0000000000..5527acaa2c --- /dev/null +++ b/artifacts/rhdh-plugins-reference/quickstart/quickstart-plugin-user.adoc @@ -0,0 +1,72 @@ +[id="using-quickstart-plugin"] += Using the Quickstart plugin + +The Quickstart plugin provides a guided onboarding experience for new users of {product}. It displays a customizable drawer interface with interactive quickstart steps that help users get familiar with the platform. + +== Features +Interactive Drawer Interface:: Displays quickstart steps in a slide-out drawer. +Progress Tracking:: Tracks completion status of individual steps with persistent storage. +Configurable Content:: Define custom quickstart items through app configuration. +Visual Progress Indicator:: Shows overall completion progress with a progress bar. +Call-to-Action Support:: Each step can include clickable action buttons. + +.Procedure +. Open the Quickstart drawer +.. Navigate to the **top right corner** of the {product-short} interface. +.. Click the icon labeled **“Quick start”** (represented by a question mark icon in the top menu). +.. The drawer panel on the **right-hand side** of the screen slides open. + +. Review the available Quickstart items ++ +In the drawer, you will see a list of onboarding tasks, including: + +Set up authentication:: +Configure secure login credentials to protect your account. + +Configure RBAC:: + Set up Role-Based Access Control for your team. + +Configure Git:: + Connect your Git repositories for source control and automation. + +Manage plugins:: + Enable or disable additional functionality in the Hub. ++ +Each item may be expandable and interactive. + +. Track Your Progress +* Each Quick Start item includes a **status indicator**, such as: + ** _Not started_ + ** _In progress_ + ** _Completed_ ++ +As you complete each step or task, your progress is automatically tracked. + +[NOTE] +==== +Quickstart items are **configurable**, meaning the content and order can vary depending on your Red Hat Developer Hub instance. + +You can **revisit** or **reset** tasks at any time for review or team onboarding. + +You can hide the Quickstart drawer by clicking *Hide* +==== + +//// += Using the Context Hook +Access quickstart drawer functionality in your components: + +[source,yaml] +---- +import { useQuickstartDrawerContext } from '@red-hat-developer-hub/backstage-plugin-quickstart'; + +const MyComponent = () => { + const { openDrawer, closeDrawer, isDrawerOpen } = + useQuickstartDrawerContext(); + + return ; +}; +---- +//// + += Progress persistence +The plugin automatically saves progress, so users can continue where they left off even after refreshing the page or returning later. diff --git a/assemblies/assembly-configuring-the-quickstarts.adoc b/assemblies/assembly-configuring-the-quickstarts.adoc new file mode 100644 index 0000000000..a8ad516cda --- /dev/null +++ b/assemblies/assembly-configuring-the-quickstarts.adoc @@ -0,0 +1,10 @@ +:_mod-docs-content-type: ASSEMBLY +:context: customizing-the-quickstarts +[id="{context}"] += Customizing the Quickstart plugin + +include::modules/configuring-the-quickstarts/con-about-quickstarts.adoc[leveloffset=+1] + +include::modules/configuring-the-quickstarts/proc-customize-rhdh-quickstart.adoc[leveloffset=+1] + +include::modules/configuring-the-quickstarts/proc-starting-and-completing-modules-in-quickstarts.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc index eb541ce985..c5b32e6083 100644 --- a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc @@ -16,6 +16,9 @@ include::../../artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.a // Nexus include::../../artifacts/rhdh-plugins-reference/nexus-repository-manager/nexus-repository-manager-plugin-admin.adoc[leveloffset=+1] +// Quick start +include::../../artifacts/rhdh-plugins-reference/quickstart/quickstart-plugin-admin.adoc[leveloffset=+1] + // Tekton include::../../artifacts/rhdh-plugins-reference/tekton/tekton-plugin-admin.adoc[leveloffset=+1] diff --git a/assemblies/dynamic-plugins/assembly-extensions-plugins.adoc b/assemblies/dynamic-plugins/assembly-extensions-plugins.adoc index 599533e84f..d3ca7a9280 100644 --- a/assemblies/dynamic-plugins/assembly-extensions-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-extensions-plugins.adoc @@ -32,12 +32,44 @@ include::../modules/dynamic-plugins/con-catalog-searching-and-filtering.adoc[lev // Viewing a plugin - screenshots added post 1.5 GA, so this section is no longer necessary // include::../modules/dynamic-plugins/ref-catalog-plugin.adoc[leveloffset=+2] -// Installing a plugin -include::../modules/dynamic-plugins/proc-extensions-installing.adoc[leveloffset=+1] - // Disabling Extensions include::../modules/dynamic-plugins/proc-extensions-disabling.adoc[leveloffset=+1] +// START RHDH 1.7.0 +// ========== +// Managing plugins installation by using Extensions +include::../modules/dynamic-plugins/con-extensions-managing-plugins.adoc[leveloffset=+1] + +// Configuring an RBAC role to manage Extensions +include::../modules/dynamic-plugins/proc-extensions-configuring-rbac-role.adoc[leveloffset=+2] + +// Enabling plugins installation by using Extensions +include::../modules/dynamic-plugins/proc-extensions-enabling-plugins-installation.adoc[leveloffset=+2] + +// Installing plugins by using Extensions +include::../modules/dynamic-plugins/proc-extensions-installing-plugins.adoc[leveloffset=+2] + +// Configuring plugins by using Extensions +include::../modules/dynamic-plugins/proc-extensions-configuring-plugins.adoc[leveloffset=+2] + +// Troubleshooting plugins installation by using Extensions [Stretch] +// include::../modules/dynamic-plugins/con-extensions-troubleshooting-plugins-installation.adoc[leveloffset=+1] +// ========== + +// Enabling plugins installation by using Extensions +// include::../modules/dynamic-plugins/proc-extensions-enabling.adoc[leveloffset=+1] + +// Managing plugins [TBC] +//include::../modules/dynamic-plugins/proc-extensions-managing.adoc[leveloffset=+1] + +// Installing a plugin [TBC] +//include::../modules/dynamic-plugins/proc-extensions-installing.adoc[leveloffset=+1] + +// END RHDH 1.7.0 + +// Operator installation by using plugin extension +//include::../modules/dynamic-plugins/proc-operator-installing-a-plugin-using-extensions.adoc[leveloffset=+1] + // Managing the extensions plugin entries - For 1.6+ //include::../modules/dynamic-plugins/proc-extensions-managing.adoc[leveloffset=+1] diff --git a/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc index 4d9d74eb90..519967d483 100644 --- a/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-using-rhdh-plugins.adoc @@ -16,6 +16,9 @@ include::../../artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-user.ad // Nexus include::../../artifacts/rhdh-plugins-reference/nexus-repository-manager/nexus-repository-manager-plugin-user.adoc[leveloffset=+1] +// Quickstart +include::../../artifacts/rhdh-plugins-reference/quickstart/quickstart-plugin-user.adoc[leveloffset=+1] + // Tekton include::../../artifacts/rhdh-plugins-reference/tekton/tekton-plugin-user.adoc[leveloffset=+1] diff --git a/images/rhdh/about-quickstarts.png b/images/rhdh/about-quickstarts.png new file mode 100644 index 0000000000..56e63582e4 Binary files /dev/null and b/images/rhdh/about-quickstarts.png differ diff --git a/images/rhdh/extensions-enable-plugin-1.png b/images/rhdh/extensions-enable-plugin-1.png new file mode 100644 index 0000000000..015d296e6f Binary files /dev/null and b/images/rhdh/extensions-enable-plugin-1.png differ diff --git a/images/rhdh/extensions-install-plugin-1.png b/images/rhdh/extensions-install-plugin-1.png new file mode 100644 index 0000000000..c405e7a3ad Binary files /dev/null and b/images/rhdh/extensions-install-plugin-1.png differ diff --git a/images/rhdh/extensions-install-plugin-2.png b/images/rhdh/extensions-install-plugin-2.png new file mode 100644 index 0000000000..40237dc42d Binary files /dev/null and b/images/rhdh/extensions-install-plugin-2.png differ diff --git a/images/rhdh/extensions-install-plugin-3.png b/images/rhdh/extensions-install-plugin-3.png new file mode 100644 index 0000000000..d396d223de Binary files /dev/null and b/images/rhdh/extensions-install-plugin-3.png differ diff --git a/images/rhdh/extensions-rbac-role-create.png b/images/rhdh/extensions-rbac-role-create.png new file mode 100644 index 0000000000..2730fb50cb Binary files /dev/null and b/images/rhdh/extensions-rbac-role-create.png differ diff --git a/images/rhdh/extensions-restart-plugin-1.png b/images/rhdh/extensions-restart-plugin-1.png new file mode 100644 index 0000000000..aa97392ad7 Binary files /dev/null and b/images/rhdh/extensions-restart-plugin-1.png differ diff --git a/modules/configuring-the-quickstarts/con-about-quickstarts.adoc b/modules/configuring-the-quickstarts/con-about-quickstarts.adoc new file mode 100644 index 0000000000..b578e1eeab --- /dev/null +++ b/modules/configuring-the-quickstarts/con-about-quickstarts.adoc @@ -0,0 +1,13 @@ +:_mod-docs-content-type: CONCEPT + +[id="about-quickstarts_{context}"] += About Quickstarts + +The Quickstart plugin provides a guided onboarding experience for new users of {product}. It displays a customizable drawer interface with interactive quickstart steps that help users get familiar with the platform. + +The Quickstart plugin is enabled by default and includes the following components: + +Set up authentication:: Set up secure login credentials to protect your account from unauthorized access. +Configure RBAC:: Assign roles and permissions to control who can view, create, or edit resources, ensuring secure and efficient collaboration. +Configure Git:: Connect your Git providers, such as GitHub to manage code, automate workflows, and integrate with platform features. +Manage plugins:: Browse and install extensions to add features, connect with external tools, and customize your experience. diff --git a/modules/configuring-the-quickstarts/proc-customize-rhdh-quickstart.adoc b/modules/configuring-the-quickstarts/proc-customize-rhdh-quickstart.adoc new file mode 100644 index 0000000000..74ee6a4bfb --- /dev/null +++ b/modules/configuring-the-quickstarts/proc-customize-rhdh-quickstart.adoc @@ -0,0 +1,55 @@ +[id="customizing-your-product-quickstart_{context}"] += Customizing your {product} Quickstart + +You can configure the {product} Quickstart plugin to create a customized onboarding experience for your {product-short} administrators. + +.Prerequisites +You must have sufficient permissions as a platform engineer. + +.Procedure +. Update your your `app-config.yaml`, as follows: ++ +.Example of customizing the Quickstart plugin +[source,yaml] +---- +app: + quickstart: + - title: 'Welcome to Developer Hub' # <1> + description: 'Learn the basics of navigating the Developer Hub interface' # <2> + icon: 'home' # <3> + cta: + text: 'Get Started' # <4> + link: '/catalog' # <5> + - title: 'Create Your First Component' + description: 'Follow our guide to register your first software component' + icon: 'code' + cta: + text: 'Create Component' + link: '/catalog-import' + - title: 'Explore Templates' + description: 'Discover available software templates to bootstrap new projects' + icon: 'template' + cta: + text: 'Browse Templates' + link: '/create' +---- +<1> (Required) The display title for the quickstart step. +<2> (Required) A brief description of what the step covers. +<3> Icon identifier (supports Material UI icons). +<4> CTA button text. +<5> CTA target URL or route. + +== Disabling the Quickstart plugin +The Quickstart plugin is pre-loaded in {product-short} with basic configuration properties, and enabled by default. To disable it, set the disabled property to `true` as follows: + +.Example of disabling the Quickstart plugin +[source,yaml] +---- +global: + dynamic: + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-quickstart + disabled: true +---- \ No newline at end of file diff --git a/modules/configuring-the-quickstarts/proc-starting-and-completing-modules-in-quickstarts.adoc b/modules/configuring-the-quickstarts/proc-starting-and-completing-modules-in-quickstarts.adoc new file mode 100644 index 0000000000..c135a77a92 --- /dev/null +++ b/modules/configuring-the-quickstarts/proc-starting-and-completing-modules-in-quickstarts.adoc @@ -0,0 +1,22 @@ +[id='proc-starting-and-completing-modules-in-quickstarts_{context}'] += Starting and completing Quickstart onboarding steps + +You can start and complete the Quickstart onboarding steps at your own pace. + +.Prerequisites +. Your platform engineer has granted you access to the Quickstart plugin. + +.Procedure +To start a Quickstart step in {product}, complete the following steps: + +. In your {product-very-short} navigation menu, click on the (`?`) icon. +. Click *Quick start*. +. Select the Quickstart step that you would like to begin. +. To close the Quickstart drawer, click *Hide*. ++ +image::rhdh/about-quickstarts.png[About Quickstarts] ++ +[NOTE] +==== +Your progress is tracked and displayed at the bottom of the drawer. +==== \ No newline at end of file diff --git a/modules/dynamic-plugins/con-extensions-managing-plugins.adoc b/modules/dynamic-plugins/con-extensions-managing-plugins.adoc new file mode 100644 index 0000000000..f6564d5e45 --- /dev/null +++ b/modules/dynamic-plugins/con-extensions-managing-plugins.adoc @@ -0,0 +1,19 @@ +[id="con-extensions-managing-plugins_{context}"] += Managing plugins by using Extensions + +You can install and configure plugins by using Extensions. + +[WARNING] +Installation and configuration of plugins by using Extensions will only work in development environments. This feature is not supported in production environments. + +In a production environment, users will be notified that plugin installation is not permitted. + +image::rhdh/extensions-restart-plugin-1.png[] + +In a development environment: + +* Administrators can install a plugin using the default configuration preloaded in the editor, or modify the configuration before installing. Upon successful installation, users will be notified that a backend restart is required to complete the installation process. +* When a plugin is installed, administrators can access the Actions drop-down in the plugin’s side panel. Available actions include: +** Editing the configuration used during installation +** Disabling or enabling the plugin +** After performing any of these actions, users will be notified that a backend restart is required for the changes to take effect. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-extensions-configuring-plugins.adoc b/modules/dynamic-plugins/proc-extensions-configuring-plugins.adoc new file mode 100644 index 0000000000..09bddc64b9 --- /dev/null +++ b/modules/dynamic-plugins/proc-extensions-configuring-plugins.adoc @@ -0,0 +1,27 @@ +[id="proc-extensions-configuring-plugins_{context}"] += Enabling and disabling plugins by using Extensions + +.Prerequisites +* You have configured {product-very-short} to allow plugins installation from *Extensions*. +* You have configured RBAC to allow the current user to access to manage plugin configuration. + +.Procedure +. Navigate to *Extensions*. +. Select a plugin to enable or disable. +. Click on the Enable/Disable slider. ++ +image::rhdh/extensions-enable-plugin-1.png[] +. To view the plugins that require a restart, click *View plugins* in the alert message. ++ +image::rhdh/extensions-install-plugin-3.png[] +. Restart your {product-very-short} application. + +.Verification +. After you restart your {product-very-short} application, navigate to *Extensions*. +. Select the plugin that you have installed. +. The Enable/Disable slider is updated. + + + + + diff --git a/modules/dynamic-plugins/proc-extensions-configuring-rbac-role.adoc b/modules/dynamic-plugins/proc-extensions-configuring-rbac-role.adoc new file mode 100644 index 0000000000..82ba1fffba --- /dev/null +++ b/modules/dynamic-plugins/proc-extensions-configuring-rbac-role.adoc @@ -0,0 +1,48 @@ +[id="proc-extensions-configuring-rbac-role_{context}"] += Configuring RBAC to manage Extensions + +You can add Extensions permissions by creating or updating and existing RBAC role. For more information about using RBAC to manage role-based controls, see link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/authorization_in_red_hat_developer_hub/managing-authorizations-by-using-the-web-ui[Managing role-based access controls (RBAC) using the {product} Web UI]. + +== Creating a role in the {product-short} UI to manage Extensions + +.Prequisites +* You have enabled RBAC, have a policy administrator role in {product-short}, and have added plugins with permission. + +.Procedure +. Go to Administration at the bottom of the sidebar in the {product-short}. ++ +The *RBAC* tab appears, displaying all the created roles in the Developer Hub. +. Click *Create* to create a role. +. Enter the user name and description (optional) of role in the given fields and click *Next*. +. In *Add users and groups*, select the user name, and click *Next*. +. In *Add permission policies*, select *Extensions* from the plugins dropdown. +. Expand *Extensions*, select both the *Create* and *Read* permissions for the Extensions plugin and click *Next*. +. Click *Create* to create the role. ++ +image::rhdh/extensions-rbac-role-create.png[] + +.Verification +After you refresh the {product-very-short} application, when you select a plugin, the *Actions* dropdown will be active. +When you click on the *Active* dropdown, you can edit the the plugin configuration, and enable or disable the plugin. + +// Not documented +// [source,yaml] +// ---- +// p, role:default/team_a, extensions-plugin, read, allow +// p, role:default/team_a, extensions-plugin, create, allow +// g, user:default/, role:default/team_a + +// permission: +// enabled: true +// rbac: +// admin: +// users: +// - name: user:default/gerry-forde +// pluginsWithPermission: +// - catalog +// - scaffolder +// - permission +// - extensions +// ---- + + diff --git a/modules/dynamic-plugins/proc-extensions-enabling-plugins-installation.adoc b/modules/dynamic-plugins/proc-extensions-enabling-plugins-installation.adoc new file mode 100644 index 0000000000..82e18e2808 --- /dev/null +++ b/modules/dynamic-plugins/proc-extensions-enabling-plugins-installation.adoc @@ -0,0 +1,130 @@ +[id="proc-extensions-enabling-plugins-installation_{context}"] += Configuring {product-very-short} to install plugins by using Extensions + +When you install a plugin using Extensions UI, the configuration that you use is saved to a `dynamic-plugins.marketplace.yaml` file within the `dynamic-plugins-root` persistent volume. This ensures the configuration is available when you restart the application, allowing you to edit or re-enable the plugin. + +You must create a persistent volume claim (PVC) to ensure that the cache persists when you restart the {product-very-short} application. For more information about using the dynamic plugins cache, see link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/{product-version}/html-single/configuring_red_hat_developer_hub/index#using-the-dynamic-plugins-cache_running-behind-a-proxy[Using the dynamic plugins cache]. + +.Prequisites +* You have created a persistent volume claim (PVC) for the dynamic plugins cache with the name *dynamic-plugins-root*. +* You have installed Red Hat Developer Hub using the Helm chart or the Operator. +* You have installed the OpenShift CLI (`oc`). + +.Procedure +. Create the extensions configuration file and save it as `dynamic-plugins.extensions.yaml`. For example: ++ +[source,yaml] +---- +includes: + - dynamic-plugins.default.yaml + +plugins: + - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-marketplace: + appIcons: + - name: marketplace + importName: MarketplaceIcon + dynamicRoutes: + - path: /extensions/catalog + importName: DynamicMarketplacePluginRouter + mountPoints: + - mountPoint: application/provider + importName: InstallationContextProvider + - mountPoint: internal.plugins/tab + importName: DynamicMarketplacePluginContent + config: + path: marketplace + title: Catalog + - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic + disabled: false + pluginConfig: + extensions: + installation: + enabled: true + saveToSingleFile: + file: /opt/app-root/src/dynamic-plugins-root/dynamic-plugins.extensions.yaml +---- +. Copy the file to your cluster by running the following commands: ++ +[source,yaml] +---- +oc get pods -n + +oc cp ./dynamic-plugins.extensions.yaml /:/opt/app-root/src/dynamic-plugins-root/dynamic-plugins.extensions.yaml +---- + +. Update your {product-very-short} application to use this file: +.. For operator-based installations: +//... Click on the overflow menu... +... Update your Backstage CR to update the `NODE_ENV` environment variable to `development`, as follows: ++ +[source,yaml] +---- +apiVersion: rhdh.redhat.com/v1alpha3 +kind: Backstage +metadata: + name: developer-hub + namespace: rhdh +spec: + application: + dynamicPluginsConfigMapName: dynamic-plugins-rhdh + extraEnvs: + envs: + - name: NODE_ENV + value: "development" + secrets: + - name: secrets-rhdh + extraFiles: + mountPath: /opt/app-root/src + route: + enabled: true + database: + enableLocalDb: true +---- +... Update your `dynamic-plugins-rhdh` config map to include your extensions configuration file, as follows: ++ +[source,yaml] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh + namespace: rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + - /dynamic-plugins-root/dynamic-plugins.extensions.yaml + plugins: [] +---- + + +.. For Helm chart installations: + +... Upgrade the Helm release to include your extensions configuration file and update the `NODE_ENV` environment variable to `development`: ++ +[source,yaml] +---- +global: + auth: + backend: + enabled: true + clusterRouterBase: apps..com + dynamic: + includes: + - dynamic-plugins.default.yaml + - /dynamic-plugins-root/dynamic-plugins.extensions.yaml +upstream: + backstage: + extraEnvVars: + - name: NODE_ENV + value: development +---- +... Click *Upgrade* + +.Verification +Enable a plugin by using the Extensions UI, restart your {product-very-short} application and refresh the UI to confirm that the plugin is enabled. \ No newline at end of file diff --git a/modules/dynamic-plugins/proc-extensions-enabling.adoc b/modules/dynamic-plugins/proc-extensions-enabling.adoc new file mode 100644 index 0000000000..b5f316a984 --- /dev/null +++ b/modules/dynamic-plugins/proc-extensions-enabling.adoc @@ -0,0 +1,51 @@ +[id="rhdh-extensions-plugins-enabling_{context}"] += Enabling plugins installation by using Extensions +Using the extensions UI, the extensions backend now requires additional configuration in the app config, users must explicitly enable the installation and specify the file path from which the plug-in configuration should be read if the file path is missing or invalid installation will be disabled. + +[NOTE] +When you visit *Extensions*, before you enable extensions plugin installation, you will see an information message saying that the plugin installation is disabled. + +.Prerequisites +* You added a custom Developer Hub application configuration, and have sufficient permissions to modify it. +* You are in development mode. +* You have created the plugin configuration file and added the file path in your `app-config.yaml` file. +* You have the correct RBAC permissions. +// * You have installed the `oc` CLI [TBC]. + +//// +ISSUES +I dont't see a warning message when I access RHDH in production mode - Is this the latest version? +Configure RBAC +Add PVC +//// + +.Procedure +. Switch to *development* mode by editing your app-config.yaml file as follows: ++ +.`app-config.yaml` fragment +[source,yaml] +---- +auth: + environment: development # Set to 'development' for development mode + providers: + # ... your providers configured for development mode ... + guest: # Example: Guest provider often has specific settings for dev + dangerouslyAllowOutsideDevelopment: true # Allows guest login outside of dev mode only if explicitly enabled +---- +. Create a plugin configuration file to store plugin configuration data when you enable a plugin by using Extensions. +// dynamic-plugins-test.yaml as configmap + +. To enable extensions plugin installation, you must update your `app-config.yaml` file as follows: ++ +.`app-config.yaml` fragment +[source,yaml] +---- +extensions: + installation: + enabled: true + saveToSingleFile: + file: //dynamic-plugins.yaml +---- + +[NOTE] +If a specific plug-in configuration is not found in the provided file, it will fall back to fetching it from the dynamic artifacts. diff --git a/modules/dynamic-plugins/proc-extensions-installing-plugins.adoc b/modules/dynamic-plugins/proc-extensions-installing-plugins.adoc new file mode 100644 index 0000000000..5ae2333c57 --- /dev/null +++ b/modules/dynamic-plugins/proc-extensions-installing-plugins.adoc @@ -0,0 +1,34 @@ +[id="proc-extensions-installing-plugins_{context}"] += Installing plugins by using Extensions +You can install and configure plugins by using Extensions. + +.Prequisites +* You have configured {product-very-short} to allow plugins installation from *Extensions*. +* You have configured RBAC to allow the current user to manage plugin configuration. + +.Procedure +. Navigate to *Extensions*. +. Select a plugin to install. +. Click on the *Install* button. ++ +image::rhdh/extensions-install-plugin-1.png[] +The code editor is displayed which displays the plugin default configuration. +. Update the plugin configuration, if necessary. ++ +image::rhdh/extensions-install-plugin-2.png[] +. Click *Install* +. To view the plugins that require a restart, click *View plugins* in the alert message. ++ +image::rhdh/extensions-install-plugin-3.png[] +. Restart your {product-very-short} application. + +.Verification +. After you restart your {product-very-short} application, navigate to *Extensions*. +. Select the plugin that you have installed. +. The *Actions* button is displayed. +// . Click on *Edit* to view the configuration that you used to install the plugin. + + + + + diff --git a/modules/dynamic-plugins/proc-extensions-installing.adoc b/modules/dynamic-plugins/proc-extensions-installing.adoc index 7f3ed66f1b..29bae7b313 100644 --- a/modules/dynamic-plugins/proc-extensions-installing.adoc +++ b/modules/dynamic-plugins/proc-extensions-installing.adoc @@ -1,11 +1,19 @@ [id="rhdh-extensions-plugins-installing_{context}"] = Installing a plugin by using Extensions + +[WARNING] +Installation and configuration of plugins by using Extensions will only work in development environments. This feature is not supported in production environments. + You can install a plugin and configure it by updating the `dynamic-plugins.yaml` file by using *Extensions*. -== Prerequisites +.Prerequisites +* Your {product-short} instance running development mode. +* You have enabled installation of plugins by Extensions. * You have the necessary permissions to modify plugin configurations and access the application environment. * You have identified and set the required environment variables referenced by the plugin's default configuration. These environment variables must be defined in the Helm Chart or Operator configuration. + + .Procedure . Open your {product-short} application and click *Administration* > *Extensions*. . Use the search bar on the *Extensions* page to find the plugin you wish to install, then click on the card. For example, search for Tekton and click *Read more* on the *Pipelines With Tekton* card. @@ -21,36 +29,52 @@ image::rhdh-plugins-reference/rhdh-extensions-tekton-editor-1.png[Extensions cat . Click the *Examples* tab to display the default plugin configuration. . Click *Apply* to copy the default plugin configuration to the YAML editor. . In the YAML editor, click the copy icon to copy the plugin configuration. +[TODO] Update screenshot to include active Install button. + image::rhdh-plugins-reference/rhdh-extensions-tekton-editor-2.png[Extensions catalog with Tekton configuration] -+ -[NOTE] -In {product-very-short} {product-version}, the *Install* button is disabled, so you must copy the plugin configuration to the `dynamic-plugins.yaml` file. -. In the `dynamic-plugins.yaml` file, add the plugin configuration that you copied in the previous step to the `plugins` definitions. +. Click *Install* to install the plugin. + +// See also https://gitlab.cee.redhat.com/rhidp/rhdh-team-docs/-/blob/main/docs/teams/ui/plugins-setup-guide.md?ref_type=heads#servicenow for exapmle of installing Service Now from extensions + +// + +// [NOTE] +// In {product-very-short} {product-version}, the *Install* button is disabled, so you must copy the plugin configuration to the `dynamic-plugins.yaml` file. +// . In the `dynamic-plugins.yaml` file, add the plugin configuration that you copied in the previous step to the `plugins` definitions. + [NOTE] If you have installed {product-very-short} by using the Helm Chart, to enable the plugin, you may need to roll out your {product-very-short} project manually. ++ +[TODO] Add step about message being displayed to restart pod, remove previous note and include screenshot. + + +Once the RHDH pod is running, navigate to the extensions plugin. +Select any plugin that you would like to install. +The install button is disabled because the current user does not have access to manage plugin configurations. +In RBAC, we need to create a role for this user to enable plugin installation. + +Select extensions from the plugin dropdown, expand it to view the newly added permissions for the extensions plugin. +Select both and click next to create the role. +Refresh the application +Now when I navigate to the extensions plugin and click on a plugin I see an Actions dropdown which means the plugin is preinstalled for me and I now have the access to edit or disable the plugin. + +If I disable the plugin, I’m notified to restart the backend to complete the action. + +Before I restart let’s install a plugin. +I’ll filter out the custom plugins, and select the Service Now plugin + +I can see that the plugin is not already installed, so I’ll click on Install which takes me to the code editor. If I want to make any changes to this plugin configuration, I can. I’ll apply the default configuration for the front-end package: + +You can add a comment and click Install +In this alert you can view all the plugins that require a backend restart + +Switch to my Openshift application and restart my RHDH pod (scale down/up). +Once the pod is running, switch back to your RHDH application and refresh the browser. +Verification +Switch to the Adoption Insights plugin and I can see that it is disabled. The Service Now plugin shows the Actions dropdown with the option to edit and disable the plugin. +If I click on Edit, the configuration that I used to install the plugin has been loaded in the editor. + .Verification . Click on *Administration* > *Extensions*. . Go to the *Installed* tab to view a list of installed plugins. . Search for the plugin that you installed to confirm that it is available and enabled. - -//// -. To disable the the Extensions feature plugins, edit your `dynamic-plugins.yaml` with the following content. -+ -.`dynamic-plugins.yaml` fragment -[source,yaml] ----- -plugins: - - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace - disabled: true - - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-catalog-backend-module-marketplace-dynamic - disabled: true - - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic - disabled: true ----- - -[NOTE] -If you disable the Extensions feature plugins, the *Catalog* and *Installed* tabs will also be removed. You can still view installed plugins by clicking on *Administration* > *Extensions*. -//// diff --git a/modules/dynamic-plugins/proc-extensions-managing.adoc b/modules/dynamic-plugins/proc-extensions-managing.adoc index 61485e53fe..1f4160d8fc 100644 --- a/modules/dynamic-plugins/proc-extensions-managing.adoc +++ b/modules/dynamic-plugins/proc-extensions-managing.adoc @@ -1,27 +1,237 @@ [id="rhdh-extensions-plugins-managing_{context}"] -= Managing Extensions plugin metadata in {product} += Managing plugins by using Extensions -You must add the Extensions catalog entities to your {product-very-short} container image by updating your `app-config.yaml` file, +[WARNING] +Installation and configuration of plugins by using Extensions will only work in development environments. This feature is not supported in production environments. + +You can install and configure plugins by using Extensions. When you install a plugin by using Extensions, the configuration for the plugin is saved to a dynamic plugins cache. This ensures that the configuration is available when you edit a plugin configuration. To persist the cache when the {product-very-short} pod restarts, you must create a persistent volume claim (PVC) and configured in the Helm chart. + +// I’m going to walk you through the end-to-end flow of how plugins can be installed in a development environment using the Extensions feature in the Red Hat Developer Hub. +// [NOTE] +// This installation feature is currently only meant for development environments. It is not supported in production environments yet. + +// Plugin configuration and installation +// When installing a plugin, the configuration that is used during installing is saved to a dynamic plugins cache. This ensures that the same configuration is available when editing or re-enabling the plugin. The persist the cache across pod restarts, a persistent volume claim must be created and configured in the Helm chart. .Prerequisites -* You have installed the `marketplace` plugin. +* You added a custom {product} ({product-very-short}) application configuration, and have sufficient permissions to modify it. +* You have configured {product-very-short} to install dynamic plugins. +* You have created a persistent volume (PVC) for the dynamic plugin cache. +* You have a user with required permissions [TBC] .Procedure -. Update the `catalog.locations` definition in your `app-config.yaml` file, as follows: -+ -[source,yaml] ----- -appConfig: - catalog: - rules: - - allow: [Component, System, API, Resource, Location, PluginCollection, Plugin, Package] - locations: - - type: file - target: /marketplace/catalog-entities/plugins/all.yaml - rules: - - allow: [Location, Plugin] - - type: file - target: /marketplace/catalog-entities/packages/all.yaml - rules: - - allow: [Location, Package] ----- \ No newline at end of file +//. Create a PVC with the name `dynamic-plugins-route`. This will be used in the Helm chart values when deploying the {product-very-short}. + +//// +. Create the PVC and save it to a file, such as `pvc.yaml`. For example: ++ +.`pvc.yaml` fragment +[source,yaml] +---- +kind: PersistentVolumeClaim +apiVersion: v1 +metadata: + name: dynamic-plugins-root +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi +---- + +. To apply this PVC to your cluster, run the following command: ++ +[source,yaml] +---- +oc apply -f pvc.yaml +---- + +. Configure the Helm chart to replace the ephermal volume claim with the PVC. For example: ++ +[source,yaml] +---- +upstream: + backstage: + extraVolumes: + - name: dynamic-plugins-root + persistentVolumeClaim: + claimName: dynamic-plugins-root +---- +//// +// Now if i go to the extra volumes under upstream backstage app config, I’ll replace the ephermal volume claim with the PVC volume claim that I just created. + +//. Create the Helm Release. + +. Create a marketplace configuration file and save it to `dynamic-plugins.marketplace.yaml`. For example: ++ +.`dynamic-plugins.marketplace.yaml` fragment +[source,yaml] +---- +plugins: + - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic + disabled: false + pluginConfig: + extensions: + installation: + enabled: true + saveToSingleFile: + file: /opt/app-root/src/dynamic-plugins-root/dynamic-plugins.marketplace.yaml + - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-marketplace: + appIcons: + - name: marketplace + importName: MarketplaceIcon + dynamicRoutes: + - path: /extensions/catalog + importName: DynamicMarketplacePluginRouter + mountPoints: + - mountPoint: application/provider +---- + +. Copy the file to the cluster by running the following commands: ++ +[source,yaml] +---- +oc get pods -n +oc cp ./dynamic-plugins.marketplace.yaml /:/opt/app-root/src/dynamic-plugins-root/dynamic-plugins.marketplace.yaml + +---- +. For a Helm installation: +.. For a Helm installation, upgrade helm to use this file and update environment variable to development: ++ +[source,yaml] +---- +global: + auth: + backend: + enabled: true + clusterRouterBase: apps.rosa.iuosa-vcqyd-ek4.jryo.p3.openshiftapps.com + dynamic: + includes: + - dynamic-plugins.default.yaml + - /dynamic-plugins-root/dynamic-plugins.marketplace.yaml +upstream: + backstage: + extraEnvVars: + - name: NODE_ENV + value: development +---- +.. For an Operator installation, update your Backstage CR to update environment variable NODE_ENV since this feature is disabled for ‘production’: ++ +[source,yaml] +---- +apiVersion: rhdh.redhat.com/v1alpha3 +kind: Backstage +metadata: + name: developer-hub + namespace: rhdh +spec: + application: + dynamicPluginsConfigMapName: dynamic-plugins-rhdh + extraEnvs: + envs: + - name: NODE_ENV + value: "development" + secrets: + - name: secrets-rhdh + extraFiles: + mountPath: /opt/app-root/src + route: + enabled: true + database: + enableLocalDb: true +---- ++ +Update your dynamic-plugins-rhdh to add marketplace config file and update marketplace backend config (dynamic-plugins-rhdh is from prereq 2, specified in your Backstage CR under application.appConfig.dynamicPluginsConfigMapName) ++ +[source,yaml] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh + namespace: rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + - /dynamic-plugins-root/dynamic-plugins.marketplace.yaml + plugins: [] +---- ++ +Add the following configuration for the extensions ui package in your dynamic-plugins config map, to include the new mount point ++ +[source,yaml] +---- +- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-marketplace: + appIcons: + - name: marketplace + importName: MarketplaceIcon + dynamicRoutes: + - path: /extensions/catalog + importName: DynamicMarketplacePluginRouter + mountPoints: + - mountPoint: application/provider + importName: InstallationContextProvider + - mountPoint: internal.plugins/tab + importName: DynamicMarketplacePluginContent + config: + path: marketplace + title: Catalog +---- + +.Verification +Enable some plugin via UI that is defaultly disabled, restart and see the change. + + + + + +//// +Manually create a YAML file containing our new extensions backend configuration. The extensions plugin requires the installation to be set to true and a YAML file where your plugin configurations will be written to. +I have created a local file named dynamic-plugins.marketplace.yaml and added the extensions configuration to it. I have specified the file path to be /opt/app-root/src/dynamic-plugins-root/dynamic-plugins.marketplace.yaml + +Now, copy the file to the RHDH pod, fetch the pods running under my namespace. Copy the yaml file to the rhdh pod. + +Finally, I’ll upgrade the RHDH helm release to point to this dynamic plugins marketplace yaml. So under global dynamic includes, I’ll add /dynamic-plugins-root/dynamic plugins marketplace yaml. +Click upgrade +In my dynamic plugins config map, I have added the extensions UI package configuration to include the newly added mount point: + +Once the RHDH pod is running, navigate to the extensions plugin. +Select any plugin that you would like to install. +The install button is disabled because the current user does not have access to manage plugin configurations. +In RBAC, we need to create a role for this user to enable plugin installation. + +Select extensions from the plugin dropdown, expand it to view the newly added permissions for the extensions plugin. +Select both and click next to create the role. +Refresh the application +Now when I navigate to the extensions plugin and click on a plugin I see an Actions dropdown which means the plugin is preinstalled for me and I now have the access to edit or disable the plugin. + +If I disable the plugin, I’m notified to restart the backend to complete the action. + +Before I restart let’s install a plugin. +I’ll filter out the custom plugins, and select the Service Now plugin + +I can see that the plugin is not already installed, so I’ll click on Install which takes me to the code editor. If I want to make any changes to this plugin configuration, I can. I’ll apply the default configuration for the front-end package: + +You can add a comment and click Install +In this alert you can view all the plugins that require a backend restart + +Switch to my Openshift application and restart my RHDH pod (scale down/up). +Once the pod is running, switch back to your RHDH application and refresh the browser. +Verification +Switch to the Adoption Insights plugin and I can see that it is disabled. The Service Now plugin shows the Actions dropdown with the option to edit and disable the plugin. +If I click on Edit, the configuration that I used to install the plugin has been loaded in the editor. +//// + + diff --git a/modules/dynamic-plugins/proc-operator-installing-a-plugin-using-extensions.adoc b/modules/dynamic-plugins/proc-operator-installing-a-plugin-using-extensions.adoc new file mode 100644 index 0000000000..f9611018e0 --- /dev/null +++ b/modules/dynamic-plugins/proc-operator-installing-a-plugin-using-extensions.adoc @@ -0,0 +1,104 @@ +[id="rhdh-operator-installing-a-plugin-using-extensions_{context}"] += Installing a plugin by using Extensions for Operator` +You can install a plugin and configure it by using *Extensions*. + +.Prerequisites +* you have setup RHDH with operator https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/release-1.6/install-rhdh-ocp/#assembly-install-rhdh-ocp-operator +* You have setup dynamic plugins +https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.6/html/installing_and_viewing_plugins_in_red_hat_developer_hub/rhdh-installing-rhdh-plugins_title-plugins-rhdh-about#proc-config-dynamic-plugins-rhdh-operator_rhdh-installing-rhdh-plugins +* You have setup PVC for dynamic-plugin-cache https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.6/html/configuring_red_hat_developer_hub/using-the-dynamic-plugins-cache_running-behind-a-proxy#proc-creating-a-pvc-for-the-dynamic-plugin-cache-by-using-the-operator_running-behind-a-proxy +* You have enabled RBAC and you have a user with required permissions + +.Procedure + +. Manually create marketplace configuration file dynamic-plugins.marketplace.yaml in the PVC + +.. Create marketplace configuration file dynamic-plugins.marketplace.yaml ++ +[source,javascript] +---- +echo -e "plugins:\n - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic\n disabled: false\n pluginConfig:\n extensions:\n installation:\n enabled: true\n saveToSingleFile:\n file: /opt/app-root/src/dynamic-plugins-root/dynamic-plugins.marketplace.yaml" > dynamic-plugins.marketplace.yaml +---- +.. Add the following configuration for the extensions ui package, to include the new mount point ++ +[source,yaml] +---- +- package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace + disabled: false + pluginConfig: + dynamicPlugins: + frontend: + red-hat-developer-hub.backstage-plugin-marketplace: + appIcons: + - name: marketplace + importName: MarketplaceIcon + dynamicRoutes: + - path: /extensions/catalog + importName: DynamicMarketplacePluginRouter + mountPoints: + - mountPoint: application/provider + importName: InstallationContextProvider + - mountPoint: internal.plugins/tab + importName: DynamicMarketplacePluginContent + config: + path: marketplace + title: Catalog +---- + +.. Copy the file to cluster ++ +To get rhdh : +[source,shell] +---- +kubectl get pods -n + +kubectl cp ./dynamic-plugins.marketplace.yaml /:/opt/app-root/src/dynamic-plugins-root/dynamic-plugins.marketplace.yaml +---- + +. Edit Backstage + +Update your Backstage CR to update environment variable NODE_ENV since this feature is disabled for ‘production’: + +apiVersion: rhdh.redhat.com/v1alpha3 +kind: Backstage +metadata: + name: developer-hub + namespace: rhdh +spec: + application: + dynamicPluginsConfigMapName: dynamic-plugins-rhdh + extraEnvs: + envs: + - name: NODE_ENV + value: "development" + secrets: + - name: secrets-rhdh + extraFiles: + mountPath: /opt/app-root/src + route: + enabled: true + database: + enableLocalDb: true + + + +3. Update your dynamic-plugins-rhdh to add marketplace config file and update marketplace backend config (dynamic-plugins-rhdh is from prereq 2, specified in your Backstage CR under application.appConfig.dynamicPluginsConfigMapName) ++ +[source,yaml] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + name: dynamic-plugins-rhdh + namespace: rhdh +data: + dynamic-plugins.yaml: | + includes: + - dynamic-plugins.default.yaml + - /dynamic-plugins-root/dynamic-plugins.marketplace.yaml + plugins: [] +---- + +.Verification +Enable some plugin via UI that is defaultly disabled, restart and see the change + diff --git a/modules/release-notes/ref-release-notes-new-features.adoc b/modules/release-notes/ref-release-notes-new-features.adoc index a9fe742256..cebbccd2d6 100644 --- a/modules/release-notes/ref-release-notes-new-features.adoc +++ b/modules/release-notes/ref-release-notes-new-features.adoc @@ -4,5 +4,10 @@ This section highlights new features in {product} {product-version}. -None. +[id="feature-rhidp-7663"] +== {product-short} community plugins updated to Backstage 1.39 + +The {product-short} community plugins have been updated to Backstage version 1.39. + + diff --git a/titles/customizing/master.adoc b/titles/customizing/master.adoc index 52fdfd7920..d5c480b50e 100644 --- a/titles/customizing/master.adoc +++ b/titles/customizing/master.adoc @@ -30,6 +30,8 @@ include::assemblies/assembly-configuring-the-global-header.adoc[leveloffset=+1] include::assemblies/assembly-configuring-a-floating-action-button.adoc[leveloffset=+1] +include::assemblies/assembly-configuring-the-quickstarts.adoc[leveloffset=+1] + include::assemblies/assembly-customizing-the-tech-radar-page.adoc[leveloffset=+1]