diff --git a/.vale-styles/config/vocabularies/RHDH/accept.txt b/.vale-styles/config/vocabularies/RHDH/accept.txt index 907ac9240c..b6c171fff1 100644 --- a/.vale-styles/config/vocabularies/RHDH/accept.txt +++ b/.vale-styles/config/vocabularies/RHDH/accept.txt @@ -1 +1,6 @@ +cron +Entra +IdP +Operator +MSGraph scaffolder diff --git a/.vale.ini b/.vale.ini index 3993bb9a9a..424c5c03e7 100644 --- a/.vale.ini +++ b/.vale.ini @@ -23,3 +23,4 @@ BasedOnStyles = RedHat,DeveloperHub,AsciiDocDITA AsciiDocDITA.AttributeReference = NO AsciiDocDITA.ShortDescription = NO AsciiDocDITA.CrossReference = NO +AsciiDocDITA.ConditionalCode = NO diff --git a/artifacts/attributes.adoc b/artifacts/attributes.adoc index 951a196846..7aea302480 100644 --- a/artifacts/attributes.adoc +++ b/artifacts/attributes.adoc @@ -12,11 +12,11 @@ :product-very-short: RHDH :product-local: Red Hat Developer Hub Local :product-local-very-short: RHDH Local -:product-version: 1.7 -:product-bundle-version: 1.7.0 -:product-chart-version: 1.7.0 -:product-backstage-version: 1.39.1 -:product-version-next: 1.7 +:product-version: 1.8 +:product-bundle-version: 1.8.0 +:product-chart-version: 1.8.0 +:product-backstage-version: 1.42.5 +:product-version-next: 1.9 :product-custom-resource-type: Backstage :product-docs-url: https://docs.redhat.com/en/documentation/red_hat_developer_hub :product-docs-link: link:{product-docs-url}/{product-version} @@ -24,9 +24,9 @@ // Minimum and current latest supported versions :ansible-automation-platform-version: 2.4 :keycloak-version: 26.0 -:kubernetes-version: 1.24 -:ocp-version-min: 4.14 -:ocp-version: 4.18 +:kubernetes-version: 1.29 +:ocp-version-min: 4.16 +:ocp-version: 4.19 :osd-version: 4 :rhoserverless-version: 1.36 @@ -151,6 +151,8 @@ :observability-category-link: {product-docs-link}/#Observability :ocp-docs-link: link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version} :odf-docs-link: link:https://docs.redhat.com/en/documentation/red_hat_openshift_data_foundation/{ocp-version} +:orchestrator-book-link: {product-docs-link}/html-single/orchestrator_in_red_hat_developer_hub/index +:orchestrator-book-title: Orchestrator in {product} :osd-docs-link: link:https://docs.redhat.com/en/documentation/openshift_dedicated/{osd-version} :release-notes-book-link: {product-docs-link}/html-single/red_hat_developer_hub_release_notes/index :release-notes-book-title: {product} release notes diff --git a/assemblies/assembly-authenticating-with-the-guest-user.adoc b/assemblies/assembly-authenticating-with-the-guest-user.adoc index f6da71658a..4ee7c0ee98 100644 --- a/assemblies/assembly-authenticating-with-the-guest-user.adoc +++ b/assemblies/assembly-authenticating-with-the-guest-user.adoc @@ -3,8 +3,7 @@ [id="authenticating-with-the-guest-user_{context}"] = Authenticating with the Guest user -To explore {product-short} features, you can skip configuring authentication and authorization. -You can configure {product-short} to log in as a Guest user and access {product-short} features. +For trial or non-production environments, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features. include::modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc[leveloffset=+1] diff --git a/assemblies/assembly-building-and-deploying-serverless-workflows.adoc b/assemblies/assembly-building-and-deploying-serverless-workflows.adoc new file mode 100644 index 0000000000..619b4b8481 --- /dev/null +++ b/assemblies/assembly-building-and-deploying-serverless-workflows.adoc @@ -0,0 +1,45 @@ +:_mod-docs-content-type: ASSEMBLY + +ifdef::context[] +[id="assembly-building-and-deploying-serverless-workflows"] +endif::[] +:context: orchestrator-rhdh += Build and deploy serverless workflows + +To deploy a workflow and make it available in the Orchestrator plugin, follow these main steps: + +* Building workflow images +* Generating workflow manifests +* Deploying workflows to a cluster + +This process moves the workflow from your local machine to deployment on a cluster. + +// why build workflow images +include::modules/orchestrator/con-benefits-of-workflow-images.adoc[leveloffset=+1] + +// project structure +include::modules/orchestrator/con-project-structure-overview.adoc[leveloffset=+2] + +// creating and running workflows locally +include::modules/orchestrator/proc-creating-and-running-workflows.adoc[leveloffset=+2] + +// building locally and generating artifacts +include::modules/orchestrator/proc-building-locally.adoc[leveloffset=+1] + +// the script and its uses +include::modules/orchestrator/con-build-sh-script-and-its-uses.adoc[leveloffset=+2] + +// environment variables supported by the script +include::modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc[leveloffset=+2] + +// required tools +include::modules/orchestrator/con-required-tools.adoc[leveloffset=+2] + +// building the 01_basic workflow +include::modules/orchestrator/proc-building-the-01-basic-workflow.adoc[leveloffset=+2] + +// generated workflow manifests +include::modules/orchestrator/con-generated-workflow-manifests.adoc[leveloffset=+1] + +// deploy workflows on a cluster +include::modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-configuring-a-proxy.adoc b/assemblies/assembly-configuring-a-proxy.adoc index 4581b84d1d..885a36b0b6 100644 --- a/assemblies/assembly-configuring-a-proxy.adoc +++ b/assemblies/assembly-configuring-a-proxy.adoc @@ -1,4 +1,5 @@ :_mod-docs-content-type: ASSEMBLY +:previouscontext: {context} :context: running-behind-a-proxy [id="{context}"] @@ -22,3 +23,5 @@ include::modules/configuring-a-proxy/proc-configuring-proxy-in-operator-deployme include::modules/configuring-a-proxy/proc-configuring-proxy-in-helm-deployment.adoc[leveloffset=+1] +:context: {previouscontext} +!:previouscontext: diff --git a/assemblies/assembly-configuring-external-postgresql-databases.adoc b/assemblies/assembly-configuring-external-postgresql-databases.adoc index 2868f420b1..72b6e2549f 100644 --- a/assemblies/assembly-configuring-external-postgresql-databases.adoc +++ b/assemblies/assembly-configuring-external-postgresql-databases.adoc @@ -1,4 +1,5 @@ :_mod-docs-content-type: ASSEMBLY +:previouscontext: {context} :context: configuring-external-postgresql-databases [id="{context}"] @@ -22,3 +23,5 @@ include::modules/configuring-external-databases/proc-configuring-postgresql-inst include::modules/configuring-external-databases/proc-migrating-databases-to-an-external-server.adoc[leveloffset=+1] +:context: {previouscontext} +!:previouscontext: diff --git a/assemblies/assembly-configuring-high-availability.adoc b/assemblies/assembly-configuring-high-availability.adoc index 5997b9eefd..034cb12c2c 100644 --- a/assemblies/assembly-configuring-high-availability.adoc +++ b/assemblies/assembly-configuring-high-availability.adoc @@ -1,4 +1,5 @@ :_mod-docs-content-type: ASSEMBLY +:previouscontext: {context} :context: HighAvailability [id="{context}"] @@ -28,3 +29,6 @@ As an administrator, you can configure high availability by adjusting replica va include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-operator-deployment.adoc[leveloffset=+1] include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-helm-chart-deployment.adoc[leveloffset=+1] + +:context: {previouscontext} +!:previouscontext: diff --git a/assemblies/assembly-configuring-templates.adoc b/assemblies/assembly-configuring-templates.adoc index 41143c84bc..6acafde1a2 100644 --- a/assemblies/assembly-configuring-templates.adoc +++ b/assemblies/assembly-configuring-templates.adoc @@ -19,6 +19,7 @@ include::modules/customizing-templates/proc-creating-a-new-software-component-us include::modules/customizing-templates/proc-searching-and-filtering-software-templates.adoc[leveloffset=+1] include::modules/customizing-templates/proc-adding-templates.adoc[leveloffset=+1] include::modules/customizing-templates/proc-versioning-software-templates.adoc[leveloffset=+1] +include::modules/customizing-templates/proc-enabling-software-template-version-update-notifications.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources diff --git a/assemblies/assembly-configuring-the-quickstarts.adoc b/assemblies/assembly-configuring-the-quickstarts.adoc index 1d34a2d5a1..8d5801327a 100644 --- a/assemblies/assembly-configuring-the-quickstarts.adoc +++ b/assemblies/assembly-configuring-the-quickstarts.adoc @@ -8,4 +8,6 @@ include::modules/configuring-the-quickstarts/con-about-quickstarts.adoc[leveloff include::modules/configuring-the-quickstarts/proc-customize-rhdh-quickstart.adoc[leveloffset=+1] +include::modules/configuring-the-quickstarts/proc-disabling-rhdh-quickstart.adoc[leveloffset=+2] + include::modules/configuring-the-quickstarts/proc-starting-and-completing-modules-in-quickstarts.adoc[leveloffset=+1] diff --git a/assemblies/assembly-customizing-the-appearance.adoc b/assemblies/assembly-customizing-the-appearance.adoc index 00029fff46..b315a089d8 100644 --- a/assemblies/assembly-customizing-the-appearance.adoc +++ b/assemblies/assembly-customizing-the-appearance.adoc @@ -4,13 +4,15 @@ [id="{context}"] = Customizing {product} appearance +By modifying the visual aspects of the interface, organizations can align {product} with their branding guidelines and improve the overall user experience. + The following default theme configurations are available for {product}: The {product} theme:: Default theme configurations to make your developer portal look like a standard {product} instance. For more information, see xref:ref-customize-rhdh-default-rhdh_{context}[] The Backstage theme:: Default theme configurations to make your developer portal look like a standard Backstage instance. For more information, see xref:ref-customize-rhdh-default-backstage_{context}[] -You can change or disable particular parameters in a default theme or create a fully customized theme by modifying the `app-config-rhdh.yaml` file. From the `app-config-rhdh.yaml` file, you can customize common theme components, including the following: +You can change or disable particular parameters in a default theme or create a fully customized theme by modifying the `app-config-rhdh.yaml` file. From the `app-config-rhdh.yaml` file, you can customize common theme components, including the following components: * Company name and logo * Font color, size, and style of text in paragraphs, headings, headers, and buttons @@ -22,11 +24,10 @@ You can also customize some components from the {product-short} GUI, such as the include::modules/customizing-the-appearance/proc-customize-rhdh-theme-mode.adoc[leveloffset=+1] - include::modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc[leveloffset=+1] -include::modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc[leveloffset=+1] +include::modules/customizing-the-appearance/con-about-rhdh-sidebar-menuitems.adoc[leveloffset=+1] include::modules/customizing-the-appearance/proc-customize-rhdh-sidebar-menuitems.adoc[leveloffset=+2] diff --git a/assemblies/assembly-enabling-authentication-with-github.adoc b/assemblies/assembly-enabling-authentication-with-github.adoc new file mode 100644 index 0000000000..93848481ba --- /dev/null +++ b/assemblies/assembly-enabling-authentication-with-github.adoc @@ -0,0 +1,11 @@ +:_mod-docs-content-type: ASSEMBLY +:optional-steps: enable + +[id='enabling-authentication-with-github'] += Enabling authentication with GitHub + +include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1] + + +include::modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc[leveloffset=+1] + diff --git a/assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc b/assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc new file mode 100644 index 0000000000..c6399552c9 --- /dev/null +++ b/assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: ASSEMBLY +:optional-steps: disable + +[id='enabling-authentication-with-mandatory-steps-only'] += Enabling authentication in {product} (with mandatory steps only) + +include::modules/authentication/con-understanding-authentication-and-user-provisioning.adoc[leveloffset=+1] + + +include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1] + + +include::modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc[leveloffset=+1] + + +include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1] + + +include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc[leveloffset=+1] + diff --git a/assemblies/assembly-enabling-authentication.adoc b/assemblies/assembly-enabling-authentication.adoc index ba40346624..0dc5223f54 100644 --- a/assemblies/assembly-enabling-authentication.adoc +++ b/assemblies/assembly-enabling-authentication.adoc @@ -1,11 +1,9 @@ :_mod-docs-content-type: ASSEMBLY +:optional-steps: enable [id='enabling-authentication'] = Enabling authentication in {product} - - - include::modules/authentication/con-understanding-authentication-and-user-provisioning.adoc[leveloffset=+1] @@ -15,7 +13,7 @@ include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1] include::assembly-authenticating-with-rhbk.adoc[leveloffset=+1] -include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1] +include::assembly-enabling-authentication-with-github.adoc[leveloffset=+1] include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc[leveloffset=+1] diff --git a/assemblies/assembly-localization-in-rhdh.adoc b/assemblies/assembly-localization-in-rhdh.adoc new file mode 100644 index 0000000000..02bb79ac51 --- /dev/null +++ b/assemblies/assembly-localization-in-rhdh.adoc @@ -0,0 +1,14 @@ +:_mod-docs-content-type: ASSEMBLY + +[id="assembly-localization-in-rhdh_{context}"] += Localization in {product} + +include::modules/customizing-the-appearance/proc-enabling-localization-in-rhdh.adoc[leveloffset=+1] + +include::modules/customizing-the-appearance/proc-overriding-translations.adoc[leveloffset=+2] + +include::modules/customizing-the-appearance/proc-select-rhdh-language.adoc[leveloffset=+1] + +include::modules/customizing-the-appearance/con-language-persistence.adoc[leveloffset=+2] + +include::modules/customizing-the-appearance/proc-adding-localization-to-custom-plugins.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-orchestrator-rhdh.adoc b/assemblies/assembly-orchestrator-rhdh.adoc index 75ac57aa07..9d22c3875a 100644 --- a/assemblies/assembly-orchestrator-rhdh.adoc +++ b/assemblies/assembly-orchestrator-rhdh.adoc @@ -27,13 +27,16 @@ To start using Orchestrator in {product-very-short}, you must: * Import the Orchestrator software templates into the {product} catalog // orchestrator architecture -include::modules/orchestrator/con-supported-architecture-for-orchestrator.adoc[leveloffset=+1] +include::modules/orchestrator/con-architecture-overview.adoc[leveloffset=+1] + +// compatibility guide for {product} Orchestrator +include::modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc[leveloffset=+1] // provisioning plugin dependencies include::modules/orchestrator/con-orchestrator-plugin-dependencies-operator.adoc[leveloffset=+1] -// installing the components for the orchestrator plugin -include::modules/orchestrator/con-orchestrator-plugin-components.adoc[leveloffset=+1] +// enabling orchestrator plugins components +include::modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc[leveloffset=+1] // Orchestrator Infrastructure for {product} Helm chart include::modules/orchestrator/proc-helm-install-components-orchestrator-plugin.adoc[leveloffset=+2] @@ -42,5 +45,4 @@ include::modules/orchestrator/proc-helm-install-components-orchestrator-plugin.a include::modules/orchestrator/proc-manual-install-components-orchestrator-plugin.adoc[leveloffset=+2] // {product-very-short} helper script -include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+2] - +include::modules/orchestrator/proc-helper-script-overview.adoc[leveloffset=+2] \ No newline at end of file diff --git a/assemblies/assembly-provisioning-a-custom-configuration.adoc b/assemblies/assembly-provisioning-a-custom-configuration.adoc index 597286d49a..d77f7ad440 100644 --- a/assemblies/assembly-provisioning-a-custom-configuration.adoc +++ b/assemblies/assembly-provisioning-a-custom-configuration.adoc @@ -1,4 +1,5 @@ :_mod-docs-content-type: ASSEMBLY +:previouscontext: {context} :context: provisioning-and-using-your-custom-configuration [id="{context}"] @@ -27,3 +28,5 @@ include::modules/configuring/proc-mounting-additional-files-in-your-custom-confi include::modules/configuring/proc-using-the-helm-chart-to-run-rhdh-with-your-custom-configuration.adoc[leveloffset=+1] +:context: {previouscontext} +!:previouscontext: diff --git a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc index f6ec75f80a..9a812dad10 100644 --- a/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-configuring-rhdh-plugins.adoc @@ -15,17 +15,24 @@ include::assembly-enabling-configuring-jfrog.adoc[leveloffset=+1] // Keycloak - modularized include::assembly-enabling-configuring-keycloak.adoc[leveloffset=+1] + // Nexus - modularized include::assembly-enabling-configuring-nexus.adoc[leveloffset=+1] // Tekton - modularized include::../../modules/dynamic-plugins/proc-enabling-the-tekton-plugin.adoc[leveloffset=+1] -// Topology - no-change -include::assembly-install-topology-plugin.adoc[leveloffset=+1] +// Topology +include::../dynamic-plugins/assembly-install-topology-plugin.adoc[leveloffset=+1] + +// Bulk Importing +include::../assembly-bulk-importing-from-github.adoc[leveloffset=+1] +// ServiceNow include::../assembly-using-servicenow.adoc[leveloffset=+1] +// Kubernetes Custom Actions include::../assembly-using-kubernetes-custom-actions.adoc[leveloffset=+1] -include::../../modules/dynamic-plugins/proc-overriding-core-backend-services.adoc[leveloffset=+1] +// Overriding Core Backend Service Configuration +include::../modules/dynamic-plugins/proc-overriding-core-backend-services.adoc[leveloffset=+1] diff --git a/assemblies/dynamic-plugins/assembly-rhdh-installing-dynamic-plugins.adoc b/assemblies/dynamic-plugins/assembly-rhdh-installing-dynamic-plugins.adoc index 45759afa0e..d6f4ca3549 100644 --- a/assemblies/dynamic-plugins/assembly-rhdh-installing-dynamic-plugins.adoc +++ b/assemblies/dynamic-plugins/assembly-rhdh-installing-dynamic-plugins.adoc @@ -38,6 +38,10 @@ include::../modules/dynamic-plugins/ref-rh-tech-preview-plugins.adoc[leveloffset [id="rhdh-community-plugins"] include::../modules/dynamic-plugins/ref-community-plugins.adoc[leveloffset=+4] +// Deprecated plugins +[id="rhdh-deprecated-plugins"] +include::../modules/dynamic-plugins/ref-deprecated-plugins.adoc[leveloffset=+4] + // Red Hat compatible plugins [id="rhdh-compatible-plugins"] include::../modules/dynamic-plugins/ref-rh-compatible-plugins.adoc[leveloffset=+1] diff --git a/images/rhdh/customize-language-dropdown.png b/images/rhdh/customize-language-dropdown.png new file mode 100644 index 0000000000..ab668d60f3 Binary files /dev/null and b/images/rhdh/customize-language-dropdown.png differ diff --git a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc index b2f864608e..9c7ff4413a 100644 --- a/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc +++ b/modules/authentication/con-understanding-authentication-and-user-provisioning.adoc @@ -2,8 +2,7 @@ = Understanding authentication and user provisioning -This module provides an overview of how authentication and user provisioning function within {product}. -Learn about the process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step. +Learn about the authentication process from creating user and group entities in the software catalog to user sign-in, and how authentication and catalog plugins enable each step. Understanding this process is essential for successfully configuring your {product-short} instance, securing access through authorization, and enabling features that rely on synchronized user and group data. To fully enable catalog features, provision user and group data from the Identity Provider to the {product-short} software catalog. @@ -18,10 +17,14 @@ On successful authentication, the {product-short} authentication plugin, configu Configuring authentication and user provisioning is critical for several reasons. -* It secures your {product-short} instance by ensuring only authenticated users can gain access. -* It enables authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP. +* Securing your {product-short} instance by ensuring only authenticated users can gain access. +* Enabling authorization by allowing you to define access controls based on user and group memberships synchronized from your IdP. * Provisioning user and group data to the catalog is necessary for various catalog features that rely on understanding entity ownership and relationships between users, groups, and software components. -Without this provisioning step, features like displaying who owns a component in the catalog may not function correctly. ++ +[IMPORTANT] +==== +Without this provisioning step, features such as displaying who owns a catalog entity might not function correctly. +==== [TIP] ==== @@ -29,10 +32,14 @@ To explore {product-short} features in a non-production environment, you can: * To use {product-short} without external IdP, enable the guest user to skip configuring authentication and authorization, log in as the guest user, and access all {product-short} features. -* To use {product-short} without authorization policies and features relying on the software catalog, you can enable the `dangerouslyAllowSignInWithoutUserInCatalog` resolver option. This setting bypasses the check requiring a user to be in the catalog but still enforces authentication. +* To use {product-short} without authorization policies and features relying on the software catalog, you can enable the `dangerouslyAllowSignInWithoutUserInCatalog` resolver option. +This setting bypasses the check requiring a user to be in the catalog but still enforces authentication. ==== [IMPORTANT] ==== -{product-short} uses a one-way synchronization model, where user and group data flow from your Identity Provider to the {product-short} software catalog. As a result, deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies, since those entities will be recreated during the next ingestion. +{product-short} uses a one-way synchronization model, where user and group data flow from your Identity Provider to the {product-short} software catalog. +As a result, +deleting users or groups manually through the {product-short} Web UI or REST API might be ineffective or cause inconsistencies, +since {product-short} will create those entities again during the next import. ==== diff --git a/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc b/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc index c4240c0d80..809b51390d 100644 --- a/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc +++ b/modules/authentication/proc-authenticationg-with-the-guest-user-on-a-helm-based-installation.adoc @@ -3,16 +3,15 @@ [id="authenticating-with-the-guest-user-on-a-helm-based-installation_{context}"] = Authenticating with the Guest user on a Helm-based installation -On a Helm-based installation, you can configure {product-short} to log in as a Guest user and access {product-short} features. +For trial or non-production environments installed by using the {product} Helm chart, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features. .Prerequisites -* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. +* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. * You {configuring-book-link}#using-the-helm-chart-to-run-rhdh-with-your-custom-configuration[use the {product} Helm chart to run {product-short}]. .Procedure -* To enable the guest user in your {product-short} custom configuration, {configuring-book-link}#using-the-helm-chart-to-run-rhdh-with-your-custom-configuration[configure your {product} Helm Chart] with following content: +* Add following content to your {product} Helm Chart: + -.{product} Helm Chart configuration fragment [source,yaml] ---- upstream: diff --git a/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc b/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc index a0d9175dce..50ddfe5aba 100644 --- a/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc +++ b/modules/authentication/proc-authenticationg-with-the-guest-user-on-an-operator-based-installation.adoc @@ -3,16 +3,15 @@ [id="authenticating-with-the-guest-user-on-an-operator-based-installation_{context}"] = Authenticating with the Guest user on an Operator-based installation -After an Operator-based installation, you can configure {product-short} to log in as a Guest user and access {product-short} features. +For trial or non-production environments installed by using the {product} Operator, you can enable guest access to skip configuring authentication and authorization and explore {product-short} features. .Prerequisites -* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. +* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. * You {configuring-book-link}#using-the-operator-to-run-rhdh-with-your-custom-configurationn[use the {product} Operator to run {product-short}]. .Procedure -* To enable the guest user in your {product-short} custom configuration, {configuring-book-link}#provisioning-your-custom-configuration[edit your {product-short} application configuration] with following content: +* Add the following content to the `{my-app-config-file}` file: + -.`{my-app-config-file}` fragment [source,yaml] ---- auth: diff --git a/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc b/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc index 5fcf00d7c3..659e51ab43 100644 --- a/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc +++ b/modules/authentication/proc-creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog.adoc @@ -3,7 +3,8 @@ [id="creating-a-custom-transformer-to-provision-users-from-rhbk-to-the-software-catalog"] = Creating a custom transformer to provision users from {rhbk-brand-name} ({rhbk}) to the software catalog -To customize how {rhbk} users and groups are mapped to {product} entities, you can create a backend module that uses the `keycloakTransformerExtensionPoint` to provide custom user and group transformers for the Keycloak backend. +Customize how {product} provisions users and groups to {product} software catalog entities, +by creating a backend module that uses the `keycloakTransformerExtensionPoint` to offer custom user and group transformers for the Keycloak backend. .Prerequisites * You have xref:enabling-user-authentication-with-rhbk[enabled provisioning users from {rhbk-brand-name} ({rhbk}) to the software catalog]. @@ -14,9 +15,8 @@ To customize how {rhbk} users and groups are mapped to {product} entities, you c . Add your custom user and group transformers to the `keycloakTransformerExtensionPoint`. + -The following is an example of how the backend module can be defined: +The following is an example `plugins/____/src/module.ts` file defining the backend module: + -.`plugins/____/src/module.ts` [source,javascript] ---- import { @@ -63,7 +63,7 @@ export const keycloakBackendModuleTransformer = createBackendModule({ + [IMPORTANT] ==== -The module's `pluginId` must be set to `catalog` to match the `pluginId` of the `keycloak-backend`; otherwise, the module fails to initialize. +Set the module's `pluginId` to `catalog` to match the `pluginId` of the `keycloak-backend`; otherwise, the module fails to initialize. ==== . Install this new backend module into your {product-short} backend. @@ -76,16 +76,17 @@ backend.add(import(backstage-plugin-catalog-backend-module-keycloak-transformer) .Verification * {product-short} imports the users and groups each time when started. -Check the console logs to verify that the synchronization is completed. +Check the console logs to verify the synchronization result. ++ +Successful synchronization example: + -.Successful synchronization example: [source,json] ---- {"class":"KeycloakOrgEntityProvider","level":"info","message":"Read 3 Keycloak users and 2 Keycloak groups in 1.5 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"} {"class":"KeycloakOrgEntityProvider","level":"info","message":"Committed 3 Keycloak users and 2 Keycloak groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"} ---- -* After the first import is complete, navigate to the *Catalog* page and select **User** to view the list of users. +* After the first import is complete, go to the *Catalog* page and select **User** to view the list of users. * When you select a user, you see the information imported from {rhbk}. diff --git a/modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc b/modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc new file mode 100644 index 0000000000..ad26bf65fd --- /dev/null +++ b/modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc @@ -0,0 +1,47 @@ +:_mod-docs-content-type: PROCEDURE + +[id="enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider"] += Enabling user authentication with GitHub as an auxiliary authentication provider + +To allow users to access GitHub templates or plugins that require GitHub authentication, configure GitHub as an auxiliary authentication provider. This method relies on a primary authentication provider for user identity management, and skips resolving user identity from this provider. + +.Prerequisites +* You have {configuring-book-link}[added a custom {product-short} application configuration] with another authentication provider enabled, and have enough permissions to change it. + +include::snip-enabling-user-authentication-with-github-common-steps.adoc[] + +. To set up the GitHub authentication provider as an auxiliary authentication provider, add the `auth.providers.github` section to your `{my-app-config-file}` file: ++ +[source,yaml] +---- +auth: + providers: + github: + production: + clientId: ${GITHUB_CLIENT_ID} + clientSecret: ${GITHUB_CLIENT_SECRET} + disableIdentityResolution: true +---- ++ +where: +`clientId`:: +Enter the configured secret variable name: `$\{GITHUB_CLIENT_ID}`. + +`clientSecret`:: +Enter the configured secret variable name: `$\{GITHUB_CLIENT_SECRET}`. + +`disableIdentityResolution`:: +Enter `true`to skip user identity resolution for this provider to enable sign-in from an auxiliary authentication provider. +Do not enable this setting on the primary authentication provider you plan on using for sign-in and identity management. + +.Verification + +. Go to the {product-short} login page. +. Log in with your primary authentication provider account. +. In the top user menu, go to *Settings* > *Authentication Providers*. +. In the *GitHub* line, click the *Sign in* button and log in. +. In the *GitHub* line, the button displays *Sign out*. + +.Additional resources +* {integrating-with-github-book-link}[{integrating-with-github-book-title}] + diff --git a/modules/authentication/proc-enabling-user-authentication-with-github.adoc b/modules/authentication/proc-enabling-user-authentication-with-github.adoc index a86fca6716..e4f5779469 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-github.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-github.adoc @@ -3,86 +3,24 @@ [id="enabling-user-authentication-with-github"] = Enabling user authentication with GitHub -To authenticate users with GitHub, configure the GitHub authentication provider in {product} and provision the users and groups from GitHub to the {product-short} software catalog. +Authenticate users with GitHub by provisioning the users and groups from GitHub to the {product-short} software catalog, and configuring the GitHub authentication provider in {product}. .Prerequisites -* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. +* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. -* You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App]. -Alternatively, you can ask your GitHub administrator to prepare the required GitHub App. +include::snip-enabling-user-authentication-with-github-common-steps.adoc[] -.Procedure -. To allow {product-short} to authenticate with GitHub, create a GitHub App. -Opt for a GitHub App instead of an OAuth app to use fine-grained permissions and use short-lived tokens. - -.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration: - -GitHub App name:: -Enter a unique name identifying your GitHub App, such as `authenticating-with-rhdh-____`. - -Homepage URL:: -Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`. - -Authorization callback URL:: -Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`. - -Webhook:: -Clear "Active", as this is not needed for authentication and catalog providers. - -Organization permissions:: -Enable `Read-only` access to *Members*. - -Where can this GitHub App be installed?:: -Select `Only on this account`. - -.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*. - -.. In the *Install App* tab, choose an account to install your GitHub App on. - -.. Save the following values for the next step: - -* **Client ID** -* **Client secret** - -. To add your GitHub credentials to {product-short}, add the following key/value pairs to {configuring-book-link}#provisioning-your-custom-configuration[your {product-short} secrets]. -You can use these secrets in the {product-short} configuration files by using their respective environment variable name. - -`AUTHENTICATION_GITHUB_CLIENT_ID`:: -Enter the saved **Client ID**. - -`AUTHENTICATION_GITHUB_CLIENT_SECRET`:: -Enter the saved **Client Secret**. - -`AUTHENTICATION_GITHUB_HOST_DOMAIN`:: -Enter the GitHub host domain: `github.com`. - -`AUTHENTICATION_GITHUB_ORGANIZATION`:: -Enter your GitHub organization name, such as `____`. - -. Enable the GitHub organization provisioning plugin (`backstage-plugin-catalog-backend-module-github-org`). -This plugin ingests GitHub users and groups to the {product-short} software catalog. +. Provision GitHub users and groups to the {product-short} software catalog by adding the `catalog.providers.githubOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: + -.`dynamic-plugins.yaml` file fragment -[source,yaml] ----- -plugins: - - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org' - disabled: false ----- - -. To provision GitHub users and groups to the {product-short} software catalog, add the `catalog.providers.githubOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: -+ --- [id=githubProviderId] -.`{my-app-config-file}` fragment with mandatory `catalog.providers.githubOrg` fields [source,yaml] ---- catalog: providers: githubOrg: id: githuborg - githubUrl: "${AUTHENTICATION_GITHUB_HOST_DOMAIN}" - orgs: [ "${AUTHENTICATION_GITHUB_ORGANIZATION}" ] + githubUrl: "${GITHUB_URL}" + orgs: [ "${GITHUB_ORG}" ] schedule: frequency: minutes: 30 @@ -94,13 +32,13 @@ catalog: `id`:: Enter a stable identifier for this provider, such as `githuborg`. -Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities and/or conflicts. +Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities or conflicts. `githubUrl`:: -Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_HOST_DOMAIN}`. +Enter the configured secret variable name: `$\{GITHUB_URL}`. `orgs`:: -Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_ORGANIZATION}`. +Enter the configured secret variable name: `$\{GITHUB_ORG}`. `schedule.frequency`:: Enter your schedule frequency, in the cron, ISO duration, or "human duration" format. @@ -110,12 +48,9 @@ Enter your schedule timeout, in the ISO duration or "human duration" format. `schedule.initialDelay`:: Enter your schedule initial delay, in the ISO duration or "human duration" format. --- -. To set up the GitHub authentication provider, add the `auth.providers.github` section to the `{my-app-config-file}` file content: +. To set up the GitHub authentication provider, add the `auth.providers.github` section to your `{my-app-config-file}` file: + --- -.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with GitHub [source,yaml] ---- auth: @@ -123,8 +58,8 @@ auth: providers: github: production: - clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID} - clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET} + clientId: ${GITHUB_CLIENT_ID} + clientSecret: ${GITHUB_CLIENT_SECRET} signInPage: github ---- @@ -132,17 +67,19 @@ signInPage: github Enter `production` to disable the Guest login option in the {product-short} login page. `clientId`:: -Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_CLIENT_ID}`. +Enter the configured secret variable name: `$\{GITHUB_CLIENT_ID}`. `clientSecret`:: -Enter the configured secret variable name: `${AUTHENTICATION_GITHUB_CLIENT_SECRET}`. +Enter the configured secret variable name: `$\{GITHUB_CLIENT_SECRET}`. `signInPage`:: Enter `github` to enable the GitHub provider as your {product-short} sign-in provider. - -Optional: Consider adding the following optional fields: - -.`{my-app-config-file}` file fragment including optional fields to enable authentication with GitHub ++ +Optional: Consider adding optional fields. +ifeval::["{optional-steps}" == "disable"] +See {configuring-book-link}[{configuring-book-title}]. +endif::[] +ifeval::["{optional-steps}" == "enable"] [source,yaml,subs="+quotes"] ---- auth: @@ -150,8 +87,8 @@ auth: providers: github: production: - clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID} - clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET} + clientId: ${GITHUB_CLIENT_ID} + clientSecret: ${GITHUB_CLIENT_SECRET} callbackUrl: ____ sessionDuration: { hours: 24 } signIn: @@ -178,7 +115,10 @@ Enter the resolver list to override the default resolver: `usernameMatchingUserE + The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. + -WARNING: In production mode, only configure one resolver to ensure users are securely matched. +[WARNING] +==== +Make sure users are securely matched in production mode, by configuring only one resolver. +==== `resolver`:::: Enter the sign-in resolver name. @@ -191,13 +131,17 @@ Available resolvers: `dangerouslyAllowSignInWithoutUserInCatalog: true`:::: Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. + -WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. --- +[WARNING] +==== +Do not use `dangerouslyAllowSignInWithoutUserInCatalog` in production. Use this configuration only to explore {product-short} features. +==== +endif::[] .Verification -. To verify user and group provisioning, check the console logs. +. Verify user and group provisioning by checking the console logs. ++ +Successful synchronization example: + -.Successful synchronization example: [source,json] ---- {"class":"GithubMultiOrgEntityProvider","level":"info","message":"Reading GitHub users and teams for org: rhdh-dast","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:githuborg:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:58"} @@ -210,6 +154,5 @@ WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-sh .. Log in with a GitHub account. .Additional resources - * {integrating-with-github-book-link}[{integrating-with-github-book-title}] diff --git a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc index 3332ae82fe..f59c7f15e2 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc @@ -3,21 +3,21 @@ [id="enabling-user-authentication-with-microsoft-azure"] = Enabling user authentication with {azure-brand-name} -To authenticate users with {azure-brand-name}, configure the {azure-short} authentication provider in {product} and provision the users and groups from {azure-short} to the {product-short} software catalog. +Authenticate users with {azure-brand-name} by provisioning the users and groups from {azure-short} to the {product-short} software catalog, and configuring the {azure-short} authentication provider in {product}. .Prerequisites * You have the permission to register an application in {azure-short}. Alternatively, you can ask your {azure-short} administrator to prepare the required {azure-short} application. -* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. +* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. * Your {product-short} backend can access the following hosts: `login.microsoftonline.com`:: -This is the {azure-brand-name} authorization server, which enables the authentication flow. +The {azure-brand-name} authorization server, which enables the authentication flow. `graph.microsoft.com`:: -For retrieving organization data, including user and group data, to be ingested into the {product-short} catalog. +The server for retrieving organization data, including user and group data, to import into the {product-short} catalog. .Procedure :my-product-app-name-in-azure: @@ -25,7 +25,7 @@ For retrieving organization data, including user and group data, to be ingested .. Sign in to the link:https://entra.microsoft.com/[Microsoft Entra admin center]. -.. Optional: If you have access to multiple tenants, use the *Settings* icon in the top menu to switch to the tenant in which you want to register the application from the *Directories + subscriptions* menu. +.. Optional: If you have access to many tenants, use the *Settings* icon in the top menu to switch to the tenant in which you want to register the application from the *Directories + subscriptions* menu. .. Browse to *Applications > App registrations*, and create a **New registration** with the configuration: @@ -61,7 +61,7 @@ Delegated Permissions:: `profile`::: Enter permissions that enable authenticating users. + -Optional: Enter optional custom scopes for the Microsoft Graph API that you define both in this section and in the `{my-app-config-file}` {product-short} configuration file. +Optional: Enter optional custom scopes for the Microsoft Graph API that you define both here and in your `{my-app-config-file}` {product-short} configuration file. .. On the *Applications > App registrations > __{my-product-app-name-in-azure}__ > Manage > Certificates & secrets* page, in the *Client secrets* tab, create a *New client secret*. @@ -82,24 +82,20 @@ Enter your saved *Application (client) ID*. `AUTHENTICATION_AZURE_CLIENT_SECRET`:: Enter your saved *Application (client) secret*. -. Enable the Microsoft Graph organization provisioning plugin (`backstage-plugin-catalog-backend-module-msgraph-dynamic`). -This plugin ingests {azure-short} users and groups to the {product-short} software catalog. +. Enable the Microsoft Graph organization provisioning plugin (`backstage-plugin-catalog-backend-module-msgraph-dynamic`) in your `dynamic-plugins.yaml` +file. +This plugin imports {azure-short} users and groups to the {product-short} software catalog. + -.`dynamic-plugins.yaml` file fragment [source,yaml] ---- plugins: - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic' disabled: false ---- -+ -include::{docdir}/artifacts/snip-technology-preview.adoc[] . To provision {azure-short} users and groups to the {product-short} software catalog, add the `catalog.providers.microsoftGraphOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: + --- [id=microsoftGraphOrgProviderId] -.`{my-app-config-file}` fragment with mandatory `microsoftGraphOrg` fields [source,yaml] ---- catalog: @@ -124,13 +120,13 @@ Enter `\https://graph.microsoft.com/v1.0` to define the MSGraph API endpoint the You might change this parameter to use a different version, such as the link:https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-beta#call-the-beta-endpoint[beta endpoint]. `tenandId`:: -Enter the configured secret variable name: `${AUTHENTICATION_AZURE_TENANT_ID}`. +Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_TENANT_ID}`. `clientId`:: -Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_ID}`. +Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_CLIENT_ID}`. `clientSecret`:: -Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_SECRET}`. +Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_CLIENT_SECRET}`. `schedule`:: @@ -144,15 +140,16 @@ In a large organization, user provisioning might take a long time, therefore avo `initialDelay`::: Enter the schedule initial delay in the ISO duration or human duration format. - -Optional: Consider adding the following optional `microsoftGraphOrg.providerId` fields: - ++ +Optional: Consider adding optional fields. +ifeval::["{optional-steps}" == "disable"] +See {configuring-book-link}[{configuring-book-title}]. +endif::[] +ifeval::["{optional-steps}" == "enable"] [id=authority] `authority`:: -Enter your link:https://learn.microsoft.com/en-us/graph/deployments#app-registration-and-token-service-root-endpoints[{azure-short} authority URL], -when different from the default: `\https://login.microsoftonline.com`. +Enter your link:https://learn.microsoft.com/en-us/graph/deployments#app-registration-and-token-service-root-endpoints[{azure-short} authority URL] if it is different from the default: `\https://login.microsoftonline.com`. + -.`{my-app-config-file}` fragment with optional `queryMode` field [source,yaml] ---- catalog: @@ -164,10 +161,9 @@ catalog: [id=queryMode] `queryMode: basic | advanced`:: -Enter `advanced` when the default `basic` query mode is not sufficient for your queries to the Microsoft Graph API. +Enter `advanced` when the default `basic` query mode is insufficient for your queries to the Microsoft Graph API. See link:https://learn.microsoft.com/en-us/graph/aad-advanced-queries[{azure-brand-name} advanced queries]. + -.`{my-app-config-file}` fragment with optional `queryMode` field [source,yaml] ---- catalog: @@ -184,7 +180,6 @@ Only one relationship can be expanded in a single request. See https://learn.microsoft.com/en-us/graph/query-parameters#expand-parameter[Microsoft Graph query expand parameter]. This parameter can be combined with xref:userGroupMemberFilter[`userGroupMember.filter`] or xref:userFilter[`user.filter`]. + -.`{my-app-config-file}` fragment with optional `user.expand` field [source,yaml] ---- catalog: @@ -201,7 +196,6 @@ To filter users. See link:https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties[Microsoft Graph API] and link:https://learn.microsoft.com/en-us/graph/query-parameters#filter-parameter[Microsoft Graph API query filter parameters syntax]. This parameter and xref:userGroupMemberFilter[`userGroupMember.filter`] are mutually exclusive, only one can be specified. + -.`{my-app-config-file}` fragment with optional `user.filter` field [source,yaml] ---- catalog: @@ -217,7 +211,6 @@ catalog: {product-short} loads photos by default. Enter `false` to avoid loading user photos. + -.`{my-app-config-file}` fragment with optional `user.loadPhotos` field [source,yaml] ---- catalog: @@ -232,7 +225,6 @@ catalog: `user.select`:: Enter the link:https://learn.microsoft.com/en-us/graph/api/resources/schemaextension?view=graph-rest-1.0[Microsoft Graph resource type] list to retrieve. + -.`{my-app-config-file}` fragment with optional `user.select` field [source,yaml] ---- catalog: @@ -249,7 +241,6 @@ To use group membership to get users. To filter groups and fetch their members. This parameter and xref:userFilter[`user.filter`] are mutually exclusive, only one can be specified. + -.`{my-app-config-file}` fragment with optional `userGroupMember.filter` field [source,yaml] ---- catalog: @@ -266,7 +257,6 @@ To use group membership to get users. To search for groups and fetch their members. This parameter and xref:userFilter[`user.filter`] are mutually exclusive, only one can be specified. + -.`{my-app-config-file}` fragment with optional `userGroupMember.search` field [source,yaml] ---- catalog: @@ -284,7 +274,6 @@ Only one relationship can be expanded in a single request. See link:https://learn.microsoft.com/en-us/graph/query-parameters#expand-parameter[Customize Microsoft Graph responses with query parameters]. This parameter can be combined with xref:userGroupMemberFilter[`userGroupMember.filter`] instead of xref:userFilter[`user.filter`]. + -.`{my-app-config-file}` fragment with optional `group.expand` field [source,yaml] ---- catalog: @@ -300,7 +289,6 @@ catalog: To filter groups. See link:https://learn.microsoft.com/en-us/graph/api/resources/group?view=graph-rest-1.0#properties[Microsoft Graph API query group syntax]. + -.`{my-app-config-file}` fragment with optional `group.filter` field [source,yaml] ---- catalog: @@ -316,7 +304,6 @@ catalog: To search for groups. See link:https://learn.microsoft.com/en-us/graph/search-query-parameter[Microsoft Graph API query search parameter]. + -.`{my-app-config-file}` fragment with optional `group.search` field [source,yaml] ---- catalog: @@ -331,7 +318,6 @@ catalog: `group.select`:: Enter the link:https://learn.microsoft.com/en-us/graph/api/resources/schemaextension?view=graph-rest-1.0[Microsoft Graph resource type] list to retrieve. + -.`{my-app-config-file}` fragment with optional `group.select` field [source,yaml] ---- catalog: @@ -341,12 +327,10 @@ catalog: group: select: ['id', 'displayName', 'description'] ---- --- +endif::[] . To set up the {azure-short} authentication provider, add the `auth.providers.microsoft` section to your `{my-app-config-file}` file content: + --- -.`{my-app-config-file}` file fragment with mandatory fields to enable authentication with {azure-short} [source,yaml,subs="+quotes,+attributes"] ---- auth: @@ -364,20 +348,23 @@ signInPage: microsoft Enter `production` to disable the **Guest** login option in the {product-short} login page. `clientId`:: -Enter the configured secret variable name: `${AUTHENTICATION_AZURE_CLIENT_ID}`. +Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_CLIENT_ID}`. `clientSecret`:: Enter the configured secret variable name: -`${AUTHENTICATION_AZURE_CLIENT_SECRET}`. +`$\{AUTHENTICATION_AZURE_CLIENT_SECRET}`. `tenantId`:: -Enter the configured secret variable name: `${AUTHENTICATION_AZURE_TENANT_ID}`. +Enter the configured secret variable name: `$\{AUTHENTICATION_AZURE_TENANT_ID}`. `signInPage`:: Enter `microsoft` to set the {azure-short} provider as your {product-short} sign-in provider. - -Optional: Consider adding following optional fields: - ++ +Optional: Add optional fields. +ifeval::["{optional-steps}" == "disable"] +See {configuring-book-link}[{configuring-book-title}]. +endif::[] +ifeval::["{optional-steps}" == "enable"] `domainHint`:: Optional for single-tenant applications. You can reduce login friction for users with accounts in multiple tenants by automatically filtering out accounts from other tenants. @@ -385,7 +372,6 @@ If you want to use this parameter for a single-tenant application, uncomment and If your application registration is multi-tenant, leave this parameter blank. For more information, see link:https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/home-realm-discovery-policy[Home Realm Discovery]. + -.`{my-app-config-file}` file fragment with optional `domainHint` field [source,yaml,subs="+quotes,+attributes"] ---- auth: @@ -399,9 +385,13 @@ auth: `additionalScopes`:: Optional for additional scopes. To add scopes for the application registration, uncomment and enter the list of scopes that you want to add. -The default and mandatory value lists: `'openid', 'offline_access', 'profile', 'email', 'User.Read'`. +The default and mandatory value lists following scopes: +* `openid` +* `offline_access` +* `profile` +* `email` +* `User.Read` + -.`{my-app-config-file}` file fragment with optional `additionalScopes` field [source,yaml,subs="+quotes,+attributes"] ---- auth: @@ -417,7 +407,6 @@ auth: Lifespan of the user session. Enter a duration in `ms` library (such as '24h', '2 days'), ISO duration, or "human duration" format. + -.`app-config-rhdh.yaml` fragment with optional `sessionDuration` field [source,yaml,subs="+quotes"] ---- auth: @@ -440,7 +429,6 @@ The authentication provider tries each sign-in resolver in order until it succee + WARNING: In production mode, only configure one resolver to ensure users are securely matched. + -.`app-config-rhdh.yaml` fragment with optional field to allow signing in users absent from the software catalog [source,yaml] ---- auth: @@ -475,12 +463,13 @@ This resolver looks up the user by matching their Microsoft email to the user en Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. + WARNING: Use `dangerouslyAllowSignInWithoutUserInCatalog` to explore {product-short} features, but do not use it in production. --- +endif::[] .Verification . To verify user and group provisioning, check the console logs for `MicrosoftGraphOrgEntityProvider` events. + -.Successful synchronization example: +Successful synchronization example: ++ [source] ---- 2025-06-23T13:37:55.804Z catalog info Read 9 msgraph users and 3 msgraph groups in 1.5 seconds. Committing... class="MicrosoftGraphOrgEntityProvider" taskId="MicrosoftGraphOrgEntityProvider:providerId:refresh" taskInstanceId="e104a116-6481-4ceb-9bc4-0f8f9581f959" trace_id="e4c633659cffd6b1529afa55a5bfbad7" span_id="76affd0420e8baa6" trace_flags="01" diff --git a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc index 2259e4870e..fefdc4bb7f 100644 --- a/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc +++ b/modules/authentication/proc-enabling-user-authentication-with-rhbk.adoc @@ -2,11 +2,12 @@ [id="enabling-user-authentication-with-rhbk"] = Enabling user authentication with {rhbk-brand-name} ({rhbk}) -To authenticate users with {rhbk-brand-name} ({rhbk}), enable and configure the OpenID Connect (OIDC) authentication provider in {product} and provision the users and groups from {rhbk} to the {product-short} software catalog. +Authenticate users with {rhbk-brand-name} ({rhbk}), +by provisioning the users and groups from {rhbk} to the {product-short} software catalog, and configuring the OpenID Connect (OIDC) authentication provider in {product}. .Prerequisites -* You {configuring-book-link}[added a custom {product-short} application configuration], and have sufficient permissions to modify it. -* You have sufficient permissions in {rhsso} to create and manage a realm and a client. +* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it. +* You have enough permissions in {rhsso} to create and manage a realm and a client. Alternatively, your {rhbk} administrator can prepare in {rhbk} the required realm and client for you. .Procedure @@ -19,7 +20,7 @@ Save the value for the next step: .. To register your {product-short} in {rhbk}, in the created realm, {rhbk-docs-link}/html-single/getting_started_guide/index#getting-started-zip-secure-the-first-application[secure the first application], with: ... **Client ID**: A distinctive client ID, such as __<{product-very-short}>__. ... **Valid redirect URIs**: Set to the OIDC handler URL: `pass:c,a,q[{my-product-url}/api/auth/oidc/handler/frame]`. -... Navigate to the **Credentials** tab and copy the **Client secret**. +... Go to the **Credentials** tab and copy the **Client secret**. ... Save the values for the next step: * **Client ID** * **Client Secret** @@ -27,22 +28,21 @@ Save the value for the next step: .. To prepare for the verification steps, in the same realm, get the credential information for an existing user or {rhbk-docs-link}/html-single/getting_started_guide/index#getting-started-zip-create-a-user[create a user]. Save the user credential information for the verification steps. . To add your {rhsso} credentials to {product-short}, add the following key/value pairs to {configuring-dynamic-plugins-book-link}#provisioning-your-custom-configuration[your {product-short} secrets]. -You can use these secrets in the {product-short} configuration files by using their respective environment variable name. +You can use these secrets in the {product-short} configuration files by using their environment variable name. + -`AUTHENTICATION_OIDC_CLIENT_ID`:: +`KEYCLOAK_CLIENT_ID`:: Enter the saved **Client ID**. -`AUTHENTICATION_OIDC_CLIENT_SECRET`:: +`KEYCLOAK_CLIENT_SECRET`:: Enter the saved **Client Secret**. -`AUTHENTICATION_OIDC_METADATA_URL`:: +`KEYCLOAK_BASE_URL`:: Enter the saved **{rhbk} realm base URL**. -. Enable the Keycloak organization plugin (`backstage-plugin-catalog-backend-module-keycloak-dynamic`). +. Enable the Keycloak organization plugin (`backstage-plugin-catalog-backend-module-keycloak-dynamic`) in your `dynamic-plugins.yaml` file. The plugin is named after {rhbk} upstream project. -This plugin ingests {rhbk} users and groups to the {product-short} software catalog. +This plugin imports {rhbk} users and groups to the {product-short} software catalog. + -.`dynamic-plugins.yaml` file fragment [source,yaml] ---- plugins: @@ -51,46 +51,45 @@ plugins: ---- . To provision {rhbk} users and groups to the {product-short} software catalog, add the `catalog.providers.keycloakOrg` section to your custom {product-short} `{my-app-config-file}` configuration file: - -.. Add mandatory fields: + [id=keycloakOrgProviderId] -.`{my-app-config-file}` fragment with mandatory `keycloakOrg` fields [source,yaml] ---- catalog: providers: keycloakOrg: default: - baseUrl: ${AUTHENTICATION_OIDC_METADATA_URL} - clientId: ${AUTHENTICATION_OIDC_CLIENT_ID} - clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET} + baseUrl: ${KEYCLOAK_BASE_URL} + clientId: ${KEYCLOAK_CLIENT_ID} + clientSecret: ${KEYCLOAK_CLIENT_SECRET} realm: master loginRealm: master ---- `baseUrl`:: -Enter your {rhbk} server URL, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}]. +Enter your {rhbk} server URL, defined earlier. `clientId`:: -Enter your {product-short} application client ID in {rhbk}, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}]. +Enter your {product-short} application client ID in {rhbk}, defined earlier. `clientSecret`:: -Enter your {product-short} application client secret in {rhbk}, defined when xref:enabling-user-authentication-with-rhbk[enabling authentication with {rhbk}]. +Enter your {product-short} application client secret in {rhbk}, defined earlier. `realm`:: Enter the realm name to provision users, such as `master`. `loginRealm`:: Enter the realm name to authenticate users, such as `master`. - -.. Optional: Consider adding optional fields: - ++ +Optional: Add optional fields. +ifeval::["{optional-steps}" == "disable"] +See {configuring-book-link}[{configuring-book-title}]. +endif::[] +ifeval::["{optional-steps}" == "enable"] `userQuerySize`:: Enter the user count to query simultaneously. Default value: `100`. + -.`{my-app-config-file}` fragment with optional `userQuerySize` field [source,yaml] ---- catalog: @@ -104,7 +103,6 @@ catalog: Enter the group count to query simultaneously. Default value: `100`. + -.`{my-app-config-file}` fragment with optional `groupQuerySize` field [source,yaml] ---- catalog: @@ -118,7 +116,6 @@ catalog: Enter the schedule frequency. Supports cron, ISO duration, and "human duration" as used in code. + -.`{my-app-config-file}` fragment with optional `schedule.frequency` field [source,yaml] ---- catalog: @@ -133,7 +130,6 @@ catalog: Enter the timeout for the user provisioning job. Supports ISO duration and "human duration" as used in code. + -.`{my-app-config-file}` fragment with optional `schedule.timeout` field [source,yaml] ---- catalog: @@ -148,7 +144,6 @@ catalog: Enter the initial delay to wait for before starting the user provisioning job. Supports ISO duration and "human duration" as used in code. + -.`{my-app-config-file}` fragment with optional `schedule.initialDelay` field [source,yaml] ---- catalog: @@ -158,12 +153,10 @@ catalog: schedule: initialDelay: { seconds: 15} ---- +endif::[] . To set up the {rhbk} authentication provider in your {product-short} custom configuration, edit your custom {product-short} ConfigMap such as `app-config-rhdh`, and add the following lines to the `{my-app-config-file}` content: - -.. Add mandatory fields: + -.`{my-app-config-file}` fragment with mandatory fields to enable authentication with {rhbk} [source,yaml] ---- auth: @@ -171,9 +164,9 @@ auth: providers: oidc: production: - metadataUrl: ${AUTHENTICATION_OIDC_METADATA_URL} - clientId: ${AUTHENTICATION_OIDC_CLIENT_ID} - clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET} + metadataUrl: ${KEYCLOAK_BASE_URL} + clientId: ${KEYCLOAK_CLIENT_ID} + clientSecret: ${KEYCLOAK_CLIENT_SECRET} prompt: auto signInPage: oidc ---- @@ -194,59 +187,58 @@ To allow the identity provider to automatically determine whether to prompt for ==== If `prompt: auto` is not set, the identity provider defaults to `prompt: none`, which assumes that you are already logged in and rejects sign-in requests without an active session. ==== - -.. Optional: Consider adding optional fields: - ++ +Optional: Add optional fields. +ifeval::["{optional-steps}" == "disable"] +See {configuring-book-link}[{configuring-book-title}]. +endif::[] +ifeval::["{optional-steps}" == "enable"] `callbackUrl`:: {rhbk} callback URL. + -.`{my-app-config-file}` fragment with optional `callbackURL` field [source,yaml] ---- auth: providers: oidc: production: - callbackUrl: ${AUTHENTICATION_OIDC_CALLBACK_URL} + callbackUrl: ${KEYCLOAK_CALLBACK_URL} ---- `tokenEndpointAuthMethod`:: Token endpoint authentication method. + -.`{my-app-config-file}` fragment with optional `tokenEndpointAuthMethod` field [source,yaml] ---- auth: providers: oidc: production: - tokenEndpointAuthMethod: ${AUTHENTICATION_OIDC_TOKEN_ENDPOINT_METHOD} + tokenEndpointAuthMethod: ${KEYCLOAK_TOKEN_ENDPOINT_METHOD} ---- `tokenSignedResponseAlg`:: Token signed response algorithm. + -.`{my-app-config-file}` fragment with optional `tokenSignedResponseAlg` field [source,yaml] ---- auth: providers: oidc: production: - tokenSignedResponseAlg: ${AUTHENTICATION_OIDC_SIGNED_RESPONSE_ALG} + tokenSignedResponseAlg: ${KEYCLOAK_SIGNED_RESPONSE_ALG} ---- `additionalScopes`:: Enter additional {rhbk} scopes to request for during the authentication flow. + -.`{my-app-config-file}` fragment with optional `additionalScopes` field [source,yaml] ---- auth: providers: oidc: production: - additionalScopes: ${AUTHENTICATION_OIDC_SCOPE} + additionalScopes: ${KEYCLOAK_SCOPE} ---- `signIn`:: @@ -273,9 +265,11 @@ Matches the preferred username with the user entity name. + The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed. + -WARNING: In production mode, only configure one resolver to ensure users are securely matched. +[WARNING] +==== +In production mode, only configure one resolver to ensure users are securely matched. +==== + -.`{my-app-config-file}` fragment with optional `resolvers` list [source,yaml] ---- auth: @@ -293,9 +287,11 @@ auth: `dangerouslyAllowSignInWithoutUserInCatalog: true`:::: Configure the sign-in resolver to bypass the user provisioning requirement in the {product-short} software catalog. + -WARNING: Use this option to explore {product-short} features, but do not use it in production. +[WARNING] +==== +Use this option to explore {product-short} features, but do not use it in production. +==== + -.`app-config-rhdh.yaml` fragment with optional field to allow signing in users absent from the software catalog [source,yaml] ---- auth: @@ -303,9 +299,9 @@ auth: providers: oidc: production: - metadataUrl: ${AUTHENTICATION_OIDC_METADATA_URL} - clientId: ${AUTHENTICATION_OIDC_CLIENT_ID} - clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET} + metadataUrl: ${KEYCLOAK_BASE_URL} + clientId: ${KEYCLOAK_CLIENT_ID} + clientSecret: ${KEYCLOAK_CLIENT_SECRET} signIn: resolvers: - resolver: oidcSubClaimMatchingKeycloakUserID @@ -317,7 +313,6 @@ signInPage: oidc Lifespan of the user session. Enter a duration in `ms` library format (such as '24h', '2 days'), ISO duration, or "human duration" as used in code. + -.`app-config-rhdh.yaml` fragment with optional `sessionDuration` field [source,yaml,subs="+quotes"] ---- auth: @@ -332,7 +327,6 @@ auth: `backstageTokenExpiration`::: To modify the {product-short} token expiration from its default value of one hour, note that this refers to the validity of short-term cryptographic tokens, not the session duration. The expiration value must be set between 10 minutes and 24 hours. + -.`{my-app-config-file}` fragment with optional `auth.backstageTokenExpiration` field [source,yaml,subs="+quotes"] ---- auth: @@ -347,12 +341,14 @@ For security, consider that if multiple valid refresh tokens are issued due to f . From the *Realm Settings* page, click the *Tokens* tab. . From the *Refresh tokens* section of the *Tokens* tab, toggle the *Revoke Refresh Token* to the *Enabled* position. ==== +endif::[] .Verification . To verify user and group provisioning, check the console logs. + -.Successful synchronization example: +Successful synchronization example: ++ [source] ---- 2025-06-27T16:02:34.647Z catalog info Read 5 Keycloak users and 3 Keycloak groups in 0.4 seconds. Committing... class="KeycloakOrgEntityProvider" taskId="KeycloakOrgEntityProvider:default:refresh" taskInstanceId="db55c34b-46b3-402b-b12f-2fbc48498e82" trace_id="606f80a9ce00d1c86800718c4522f7c6" span_id="7ebc2a254a546e90" trace_flags="01" diff --git a/modules/authentication/snip-enabling-user-authentication-with-github-common-steps.adoc b/modules/authentication/snip-enabling-user-authentication-with-github-common-steps.adoc new file mode 100644 index 0000000000..de3796dc0e --- /dev/null +++ b/modules/authentication/snip-enabling-user-authentication-with-github-common-steps.adoc @@ -0,0 +1,64 @@ +:_mod-docs-content-type: SNIPPET + +* You have enough permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App]. +Alternatively, you can ask your GitHub administrator to prepare the required GitHub App. + +.Procedure +. To allow {product-short} to authenticate with GitHub, create a GitHub App. +Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, use short-lived tokens, scale with the number of installations by avoiding rate limits, and have a more transparent integration by avoiding to request user input. + +.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration: + +GitHub App name:: +Enter a unique name identifying your GitHub App, such as `authenticating-with-rhdh-____`. + +Homepage URL:: +Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`. + +Authorization callback URL:: +Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`. + +Webhook:: +Clear "Active", as this is not needed for authentication and catalog providers. + +Organization permissions:: +Enable `Read-only` access to *Members*. + +Where can this GitHub App be installed?:: +Select `Only on this account`. + +.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*. + +.. In the *Install App* tab, choose an account to install your GitHub App on. + +.. Save the following values for the next step: + +* **Client ID** +* **Client secret** + +. To add your GitHub credentials to {product-short}, add the following key/value pairs to {configuring-book-link}#provisioning-your-custom-configuration[your {product-short} secrets]. +You can use these secrets in the {product-short} configuration files by using their environment variable name. + +`GITHUB_CLIENT_ID`:: +Enter the saved **Client ID**. + +`GITHUB_CLIENT_SECRET`:: +Enter the saved **Client Secret**. + +`GITHUB_URL`:: +Enter the GitHub host domain: `github.com`. + +`GITHUB_ORG`:: +Enter your GitHub organization name, such as `____`. + +. Enable the GitHub organization provisioning plugin (`backstage-plugin-catalog-backend-module-github-org`). +This plugin imports GitHub users and groups to the {product-short} software catalog. ++ +`dynamic-plugins.yaml` file fragment: ++ +[source,yaml] +---- +plugins: + - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org' + disabled: false +---- diff --git a/modules/configuring-a-floating-action-button/proc-configuring-floating-action-button-as-a-dynamic-plugin.adoc b/modules/configuring-a-floating-action-button/proc-configuring-floating-action-button-as-a-dynamic-plugin.adoc index b96fc945df..4193f14924 100644 --- a/modules/configuring-a-floating-action-button/proc-configuring-floating-action-button-as-a-dynamic-plugin.adoc +++ b/modules/configuring-a-floating-action-button/proc-configuring-floating-action-button-as-a-dynamic-plugin.adoc @@ -14,7 +14,6 @@ To configure a floating action button as a dynamic plugin, complete any of the f * Specify the `global.floatingactionbutton/config` mount point in your `app-config-dynamic.yaml` file. For example: + -.Example of a bulk-import plugin as a floating action button [source,yaml] ---- - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import @@ -26,10 +25,10 @@ To configure a floating action button as a dynamic plugin, complete any of the f # Start of the floating action button configuration mountPoints: - mountPoint: global.floatingactionbutton/config - importName: BulkImportPage # <1> + importName: BulkImportPage config: slot: 'page-end' - icon: # <2> + icon: label: 'Bulk import' toolTip: 'Register multiple repositories in bulk' to: /bulk-import/repositories @@ -44,12 +43,11 @@ To configure a floating action button as a dynamic plugin, complete any of the f icon: bulkImportIcon text: Bulk import ---- -<1> (Required) The import name with an associated component to the mount point. -<2> Use the `svg` value to display a black BulkImportPage icon. +`frontend:mountPoints:importName`:: (Required) The import name with an associated component to the mount point. +`frontend:mountPoints:importName:icon`:: Use the `svg` value to display a black `BulkImportPage` icon. * To configure an action as a floating action button that opens an external link, specify the `global.floatingactionbutton/config` mount point in your `dynamic-plugins.yaml` file within the `backstage-plugin-global-floating-action-button` plugin. For example: + -.Example of a floating action button that opens GitHub [source,yaml] ---- - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button @@ -62,9 +60,9 @@ To configure a floating action button as a dynamic plugin, complete any of the f - mountPoint: application/listener importName: DynamicGlobalFloatingActionButton - mountPoint: global.floatingactionbutton/config - importName: NullComponent # <1> + importName: NullComponent config: - icon: '' # <2> + icon: '' label: 'Quay' showLabel: true toolTip: 'Quay' @@ -77,12 +75,11 @@ To configure a floating action button as a dynamic plugin, complete any of the f toolTip: 'Github' to: https://github.com/redhat-developer/rhdh-plugins ---- -<1> (Required) The import name with an associated component to the mount point. -<2> Use the `svg` value to display the `Quay` icon. +`frontend:mountPoints:importName`:: Enter the import name with an associated component to the mount point. +`frontend:mountPoints:importName:icon`:: (Optional) Enter the icon in Scalable Vector Graphics (SVG) format to display the `Quay` icon. * To configure a floating action button that contains a submenu, define the `global.floatingactionbutton/config` mount point in the same `slot` field in your `dynamic-plugins.yaml` file for multiple actions. The default slot is `page-end` when not specified. For example: + -.Example of a floating action button with submenu actions [source,yaml] ---- - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import @@ -94,7 +91,7 @@ To configure a floating action button as a dynamic plugin, complete any of the f # Start of fab config mountPoints: - mountPoint: global.floatingactionbutton/config - importName: BulkImportPage # <1> + importName: BulkImportPage config: slot: 'page-end' icon: @@ -122,14 +119,14 @@ To configure a floating action button as a dynamic plugin, complete any of the f - mountPoint: application/listener importName: DynamicGlobalFloatingActionButton - mountPoint: global.floatingactionbutton/config - importName: NullComponent # <1> + importName: NullComponent config: icon: github label: 'Git' toolTip: 'Github' to: https://github.com/redhat-developer/rhdh-plugins - mountPoint: global.floatingactionbutton/config - importName: NullComponent # <1> + importName: NullComponent config: icon: '' label: 'Quay' @@ -137,11 +134,10 @@ To configure a floating action button as a dynamic plugin, complete any of the f toolTip: 'Quay' to: 'https://quay.io' ---- -<1> (Required) The import name with an associated component to the mount point. +`frontend:mountPoints:importName`:: (Required) The import name with an associated component to the mount point. * To configure a floating action button to display only on specific pages, configure the `global.floatingactionbutton/config` mount point in the `backstage-plugin-global-floating-action-button` plugin and set the `visibleOnPaths` property as shown in the following example: + -.Example of a floating action button to display specific pages [source,yaml] ---- - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import @@ -172,11 +168,10 @@ To configure a floating action button as a dynamic plugin, complete any of the f icon: bulkImportIcon text: Bulk import ---- -<1> (Required) The import name with an associated component to the mount point. +`frontend:mountPoints:importName`:: Enter the import name with an associated component to the mount point. * To hide a floating action button on specific pages, configure the `global.floatingactionbutton/config` mount point in the `backstage-plugin-global-floating-action-button` plugin and set the `excludeOnPaths` property as shown in the following example: + -.Example of a floating action button to hide specific pages [source,yaml] ---- - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import @@ -207,4 +202,4 @@ To configure a floating action button as a dynamic plugin, complete any of the f icon: bulkImportIcon text: Bulk import ---- -<1> (Required) The import name with an associated component to the mount point. +`frontend:mountPoints:importName`:: Enter the import name with an associated component to the mount point. diff --git a/modules/configuring-the-global-header/con-quicklinks-and-starred-items-in-global-header.adoc b/modules/configuring-the-global-header/con-quicklinks-and-starred-items-in-global-header.adoc index 37412bea07..2c9c33a075 100644 --- a/modules/configuring-the-global-header/con-quicklinks-and-starred-items-in-global-header.adoc +++ b/modules/configuring-the-global-header/con-quicklinks-and-starred-items-in-global-header.adoc @@ -9,8 +9,8 @@ The *Quicklinks* matrix, organized by sections (for example, Documentation or De The default configuration includes the following components: -*StarredDropdown*: Displays the *Starred Items* menu in the global header by default, as shown in the following configuration: - +`StarredDropdown`:: Display the *Starred Items* menu in the global header by default, as shown in the following configuration: ++ [source,yaml] ---- # Group: Global Header @@ -21,8 +21,8 @@ The default configuration includes the following components: priority: 85 ---- -*ApplicationLauncherDropdown*: Provides the *Quicklinks* matrix (application launcher) by default, as shown in the following configuration: - +`ApplicationLauncherDropdown`:: Provide the *Quicklinks* matrix (application launcher) by default, as shown in the following configuration: ++ [source,yaml] ---- # Group: Global Header @@ -33,8 +33,8 @@ The default configuration includes the following components: priority: 82 ---- -*MenuItemLink entries*: Define sections, titles, icons, and links within the *Quicklinks* matrix. The default configuration includes links to the {product-short} documentation and an {product-very-short} Local, as shown in the following configurations: - +`MenuItemLink entries`:: Define sections, titles, icons, and links within the *Quicklinks* matrix. The default configuration includes links to the {product-short} documentation and an {product-very-short} Local, as shown in the following configurations: ++ [source,yaml,subs="+attributes"] ---- - mountPoint: global.header/application-launcher @@ -61,8 +61,4 @@ The default configuration includes the following components: [NOTE] ==== When upgrading from previous versions, the installer does not overwrite your existing `dynamic-plugins.yaml` configuration. If you had not configured *Starred Items* or *Quicklinks* previously, they remain disabled after the upgrade and must be manually enabled. -==== - - - - +==== \ No newline at end of file diff --git a/modules/configuring-the-global-header/proc-configuring-logo-in-the-global-header.adoc b/modules/configuring-the-global-header/proc-configuring-logo-in-the-global-header.adoc index 32e833de39..5dadf9c23f 100644 --- a/modules/configuring-the-global-header/proc-configuring-logo-in-the-global-header.adoc +++ b/modules/configuring-the-global-header/proc-configuring-logo-in-the-global-header.adoc @@ -10,14 +10,12 @@ This component supports the following props, which are provided through configur * `logo`: The base64 encoded logo image. * `to`: The redirect path for when users click the logo is '/catalog'. * `width`: The logo width is optional and defaults to 150 px. -* `height`: The logo height is optional and defaults to 40px. +* `height`: The logo height is optional and defaults to 40 px. .Procedure . To display a custom company logo in the global header, update the configuration with a mount point for `CompanyLogo`: + -.Example: Configuring company logo -+ [source,yaml,subs="+attributes,+quotes"] ---- # ...rest of the global header configuration @@ -50,8 +48,6 @@ red-hat-developer-hub.backstage-plugin-global-header: . (Optional) If you do not provide `logo` props to the `CompanyLogo` component, the component instead uses values defined under `app.branding` in your `{my-app-config-file}` file. You can configure the `CompanyLogo` as shown in the following configuration: + -.Example: Fallback configuration -+ [source,yaml,subs="+attributes,+quotes"] ---- app: diff --git a/modules/configuring-the-global-header/proc-customize-rhdh-global-header.adoc b/modules/configuring-the-global-header/proc-customize-rhdh-global-header.adoc index c1938c2232..0635f06c3e 100644 --- a/modules/configuring-the-global-header/proc-customize-rhdh-global-header.adoc +++ b/modules/configuring-the-global-header/proc-customize-rhdh-global-header.adoc @@ -6,8 +6,6 @@ You can use the `red-hat-developer-hub.backstage-plugin-global-header` dynamic plugin to extend the global header with additional buttons and customize the order and position of icons and features. Additionally, you can create and integrate your custom dynamic header plugins using the mount points provided by this new header feature, allowing you to further tailor to suit your needs. For more information about enabling dynamic plugins, see {installing-and-viewing-plugins-book-link}[{installing-and-viewing-plugins-book-title}]. -.Default global header configuration - [source,yaml,subs="+attributes,+quotes"] ---- - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header @@ -15,11 +13,11 @@ For more information about enabling dynamic plugins, see {installing-and-viewing pluginConfig: app: sidebar: - search: false <1> - settings: false <2> + search: false + settings: false dynamicPlugins: frontend: - default.main-menu-items: <3> + default.main-menu-items: menuItems: default.create: title: '' @@ -76,12 +74,22 @@ For more information about enabling dynamic plugins, see {installing-and-viewing config: priority: 10 ---- -<1> *search*: Hides the *Search* modal in the sidebar menu. Change it to `true` to display the *Search* modal in the sidebar. -<2> *settings*: Hides the *Settings* button in the sidebar menu. Change it to `true` to display the *Settings* button in the sidebar. -<3> `default.main-menu-items`: Hides the *Self-service* button from the sidebar menu. Remove this field to display the *Self-service* button in the sidebar. -<4> *position*: Defines the position of the header. Options: `above-main-content` or `above-sidebar`. +where: + +`search`:: +Enter `false` to hide the *Search* modal in the sidebar menu. +Enter `true` to display the *Search* modal in the sidebar menu. +`settings`:: +Enter `false` to hides the *Settings* button in the sidebar menu. +Enter `true` to display the *Settings* button in the sidebar menu. +`default.main-menu-items`:: +Enter this field to hide the *Self-service* button from the sidebar menu. +Remove this field to display the *Self-service* button in the sidebar menu. +`position`:: +Enter `above-main-content` to position the header above the main content. +Enter `above-sidebar` to position the header above the sidebar. -To extend the functionality of the default global header, include any the following attributes in your global header entry: +To extend the functionality of the default global header, include any of the following attributes in your global header entry: `mountPoint`:: Specifies the location of the header. Use `application/header` to specify it as a global header. You can configure several global headers at different positions by adding entries to the `mountPoints` field. diff --git a/modules/configuring-the-global-header/proc-displaying-preferred-username-in-profile-drop-down.adoc b/modules/configuring-the-global-header/proc-displaying-preferred-username-in-profile-drop-down.adoc index a1218039f6..c29d8e0a5c 100644 --- a/modules/configuring-the-global-header/proc-displaying-preferred-username-in-profile-drop-down.adoc +++ b/modules/configuring-the-global-header/proc-displaying-preferred-username-in-profile-drop-down.adoc @@ -6,8 +6,9 @@ You can display the preferred username in the global header profile drop-down list by configuring `spec.profile.displayName` in the user entity. When not configured, the application falls back to a `metadata.title`. If neither is configured, it defaults to a user-friendly name generated by the `useProfileInfo` hook. .Procedure -.Example when you configure `spec.profile.displayName` +. To configure `spec.profile.displayName`, use the following code: ++ [source,yaml,subs="+attributes,+quotes"] ---- apiVersion: backstage.io/v1alpha1 @@ -24,8 +25,8 @@ spec: memberOf: [janus-authors] ---- -.Example when you do not configure `spec.profile.displayname` but configure `metadata.title` - +. To configure `metadata.title` rather than `spec.profile.displayname`, use the following code: ++ [source,yaml,subs="+attributes,+quotes"] ---- apiVersion: backstage.io/v1alpha1 @@ -39,8 +40,8 @@ spec: memberOf: [janus-authors] ---- -.Example when you do not configure the `spec.profile.displayname` and the `metadata.title` - +. To configure neither `spec.profile.displayname` or `metadata.title`, use the following code: ++ [source,yaml,subs="+attributes,+quotes"] ---- apiVersion: backstage.io/v1alpha1 diff --git a/modules/configuring-the-global-header/proc-enabling-logo-in-the-sidebar.adoc b/modules/configuring-the-global-header/proc-enabling-logo-in-the-sidebar.adoc index 5da014725b..e51e556148 100644 --- a/modules/configuring-the-global-header/proc-enabling-logo-in-the-sidebar.adoc +++ b/modules/configuring-the-global-header/proc-enabling-logo-in-the-sidebar.adoc @@ -7,9 +7,7 @@ You can configure a logo in the sidebar of the {product} ({product-very-short}). .Procedure -. To display the logo in the sidebar, set the value of the `app.sidebar.logo` parameter to `true` as shown in the following example: -+ -.Example: Enabling the logo in only the sidebar +. To display the logo exclusively in the sidebar, set the value of the `app.sidebar.logo` parameter to `true` as shown in the following example: + [source,yaml,subs="+attributes,+quotes"] ---- @@ -25,8 +23,6 @@ To display the logo in only the sidebar, remove the `CompanyLogo` component from . To display the same logo in the sidebar for all themes, update the configuration as shown in the following configuration: + -.Example: Configuring sidebar logo for all themes -+ [source,yaml,subs="+attributes,+quotes"] ---- app: @@ -39,8 +35,6 @@ app: . For theme-specific logos, you can configure the sidebar logo as shown in the following configuration: + -.Example: Theme-specific logos -+ [source,yaml,subs="+attributes,+quotes"] ---- app: @@ -55,4 +49,4 @@ app: .Verification . The logo appears correctly in the sidebar. -. Toggle between `light` and `dark` themes to ensure the correct logo loads in each. +. Toggle between `light` and `dark` themes to ensure the correct logo loads in each. \ No newline at end of file diff --git a/modules/configuring-the-global-header/ref-mount-points.adoc b/modules/configuring-the-global-header/ref-mount-points.adoc index 329857ae9c..319140045b 100644 --- a/modules/configuring-the-global-header/ref-mount-points.adoc +++ b/modules/configuring-the-global-header/ref-mount-points.adoc @@ -5,13 +5,14 @@ You can customize the application header in {product-short} using mount points for dynamic plugins. These mount points give flexibility in configuring the position of the header, its components and dropdown menus. You can create a customized experience with the following enhancements: -application/header:: +`application/header`:: Controls the header position. Use `config.position` to set placement as either `above-main-content` or `above-sidebar`. -global.header/component:: +`global.header/component`:: Configures header components. Use `config.priority` to set the order of components, and pass properties (including CSS styles) via `config.props`. + +`Self-service button`:: + -.Example adding a *Self-service* button [source,yaml,subs="attributes,quotes"] ---- - mountPoint: global.header/component @@ -23,8 +24,9 @@ Configures header components. Use `config.priority` to set the order of componen icon: add to: create ---- + +`Spacer element`:: + -.Example adding a spacer element [source,yaml] ---- - mountPoint: global.header/component @@ -34,8 +36,9 @@ Configures header components. Use `config.priority` to set the order of componen props: growFactor: 0 ---- + +`Divider element`:: + -.Example adding a divider element [source,yaml] ---- mountPoints: @@ -45,10 +48,12 @@ mountPoints: priority: 150 ---- -global.header/profile:: +`global.header/profile`:: Configures the profile dropdown list when the `ProfileDropdown` component is enabled. + + +* To add a settings link to the profile dropdown, use the following code: + -.Example adding a settings link to the profile dropdown [source,yaml] ---- - mountPoint: global.header/profile @@ -63,8 +68,9 @@ Configures the profile dropdown list when the `ProfileDropdown` component is ena global.header/create:: Configures the create dropdown list when the `CreateDropdown` component is enabled. + +* To add a section for registering a component, use the following code: + -.Example adding a section for registering a component [source,yaml] ---- - mountPoint: global.header/create diff --git a/modules/configuring-the-quickstarts/proc-customize-rhdh-quickstart.adoc b/modules/configuring-the-quickstarts/proc-customize-rhdh-quickstart.adoc index fd62a8ee89..8746198c22 100644 --- a/modules/configuring-the-quickstarts/proc-customize-rhdh-quickstart.adoc +++ b/modules/configuring-the-quickstarts/proc-customize-rhdh-quickstart.adoc @@ -9,19 +9,18 @@ As an administrator, you can configure the {product} Quickstart plugin to create You must have administrator permissions. .Procedure -. Update your `{my-app-config-file}`, as follows: +. Update your `{my-app-config-file}`, as shown in the following code: + -.Example of a customized Quickstart plugin [source,yaml,subs="+attributes"] ---- app: quickstart: - - title: 'Welcome to {product-short}' # <1> - description: 'Learn the basics of navigating the {product-short} interface' # <2> - icon: 'home' # <3> + - title: 'Welcome to {product-short}' + description: 'Learn the basics of navigating the {product-short} interface' + icon: 'home' cta: - text: 'Get Started' # <4> - link: '/catalog' # <5> + text: 'Get Started' + link: '/catalog' - title: 'Create Your First Component' description: 'Follow our guide to register your first software component' icon: 'code' @@ -35,23 +34,9 @@ app: 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 ----- +`title`:: Enter the display title for the quickstart step. +`description`:: Enter the brief description of what the step covers. +`icon`:: (Optional) Enter the icon identifier (supports Material UI icons). +`cta`:: +`text`::: (Optional) Enter the CTA button text. +`link`::: (Optional) Enter the CTA target URL or route. \ No newline at end of file diff --git a/modules/configuring-the-quickstarts/proc-disabling-rhdh-quickstart.adoc b/modules/configuring-the-quickstarts/proc-disabling-rhdh-quickstart.adoc new file mode 100644 index 0000000000..ad0b7acf78 --- /dev/null +++ b/modules/configuring-the-quickstarts/proc-disabling-rhdh-quickstart.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-disabling-rhdh-quickstart_{context}"] += Disabling the Quickstart plugin +The Quickstart plugin is pre-loaded in {product-short} with basic configuration properties, and enabled by default. + +.Procedure + +* To disable the Quickstart plugin, set the disabled property to `true` as shown in the following code: ++ +[source,yaml] +---- +global: + dynamic: + includes: + - dynamic-plugins.default.yaml + plugins: + - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-quickstart + disabled: true +---- diff --git a/modules/configuring/con-checklist-to-run-your-first-rhdh-instance-in-production.adoc b/modules/configuring/con-checklist-to-run-your-first-rhdh-instance-in-production.adoc new file mode 100644 index 0000000000..7bfbf66aaa --- /dev/null +++ b/modules/configuring/con-checklist-to-run-your-first-rhdh-instance-in-production.adoc @@ -0,0 +1,24 @@ +:_mod-docs-content-type: CONCEPT + +[id="checklist-to-run-your-first-rhdh-instance-in-production_{context}"] += Checklist to run your first {product} ({product-very-short}) instance in production. + +With the default configuration, {product-short} runs with a minimal feature set that does not require secure connection to external services such as an identity provider, a Git provider, and external PostgreSQL and Redis databases. + +Using critical features therefore requires following additional configuration: + +For resiliency:: +* Use an external PostgreSQL database. +* Enable high-availability. + +For performance:: +* Enable assets caching to an external Redis database. + +For security:: +* Use secure connections to your external services. +* Provision users and enable authentication. +* Enable role-based access control, and configure the permission policy by using the Web UI. + +For adapting to your environment:: +* Enable GitHub repository discovery. +* Customize {product-short} appearance with your logo. diff --git a/modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc b/modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc similarity index 98% rename from modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc rename to modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc index 8e8c6a0405..77186b221c 100644 --- a/modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc +++ b/modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc @@ -1,6 +1,6 @@ :_mod-docs-content-type: PROCEDURE -[id="proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_{context}"] +[id="configuring-an-rhdh-instance-with-tls-in-kubernetes_{context}"] = Configuring an {product-very-short} instance with a TLS connection in Kubernetes You can configure a {product-very-short} instance with a Transport Layer Security (TLS) connection in a Kubernetes cluster, such as an Azure Red Hat OpenShift (ARO) cluster, any cluster from a supported cloud provider, or your own cluster with proper configuration. Transport Layer Security (TLS) ensures a secure connection for the {product-very-short} instance with other entities, such as third-party applications, or external databases. However, you must use a public Certificate Authority (CA)-signed certificate to configure your Kubernetes cluster. diff --git a/modules/configuring/proc-preparing-your-external-services.adoc b/modules/configuring/proc-preparing-your-external-services.adoc new file mode 100644 index 0000000000..4da7ba2faf --- /dev/null +++ b/modules/configuring/proc-preparing-your-external-services.adoc @@ -0,0 +1,118 @@ +:_mod-docs-content-type: PROCEDURE + +[id="preparing-your-external-services"] += Preparing your external services + +{product} relies on external services. +Prepare the following required external services: + +PostgreSQL database:: +{product-short} stores data in a PostgreSQL database. +Use an external database for resiliency and include it in your disaster recovery plan. + +Redis cache:: +For efficiency, {product-short} caches plugin and Techdocs assets when your provide a Redis cache server. + +GitHub API access:: +Provide credentials to a GitHub app to enable access to the GitHub API for repository discovery. + +Connection to your identity provider:: +Provide credentials to your identity provider to enable user provisioning and authentication. + +.Procedure +* Get your external PostgreSQL database connection strings and certificates. +postgres-host::: Your PostgreSQL instance Domain Name System (DNS) or IP address. +postgres-port::: Your PostgreSQL instance port number, such as 5432. +postres-username::: The user name to connect to your PostgreSQL instance. +postgres-password::: The password to connect to your PostgreSQL instance. +postgres-ca.pem::: +postgres-key.key::: +postgres-crt.pem::: +For security, use TLS certificates to secure the connection to the database. + +. Get your Redis cache server connection string, such as `rediss://user:pass@cache.example.com:6379`. +For security, consider using a `rediss` secure server connection. + +. Create a GitHub App to allow {product-short} to access the GitHub API for repository. +Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, gain more control over which repositories the application can access, and use short-lived tokens. + +.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration: + +GitHub App name:: +Enter a unique name identifying your GitHub App, such as `integrating-with-rhdh-____`. + +Homepage URL:: +Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`. + +Authorization callback URL:: +Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`. + +Webhook:: +Clear "Active", as this is not needed for authentication and catalog providers. + +App permissions:: +Select permissions to define the level of access for the app. +Adapt permissions to your needs: + +Reading software components::: + +Contents:::: +`Read-only` + +Commit statuses:::: +`Read-only` + +Reading organization data::: + +Members:::: +`Read-only` + +Publishing software templates::: +Set permissions if you intend to use the same GitHub App for software templates. + +Administration:::: +`Read & write` (for creating repositories) + +Contents:::: +`Read & write` + +Metadata:::: +`Read-only` + +Pull requests:::: +`Read & write` + +Issues:::: +`Read & write` + +Workflows:::: +`Read & write` (if templates include GitHub workflows) + +Variables:::: +`Read & write` (if templates include GitHub Action Repository Variables) + +Secrets:::: +`Read & write` (if templates include GitHub Action Repository Secrets) + +Environments:::: +`Read & write` (if templates include GitHub Environments) + +Organization permissions:: +Members::: +`Read-only` + +Where can this GitHub App be installed?:: +Select `Only on this account`. + +.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*. + +.. In the *General* -> *Private keys* section, click *Generate a private key*. + +.. In the *Install App* tab, choose an account to install your GitHub App on. + +.. Save the following values for the next step: + +* **App ID** +* **Client ID** +* **Client secret** +* **Private key** diff --git a/modules/configuring/proc-provisioning-your-custom-configuration.adoc b/modules/configuring/proc-provisioning-your-custom-configuration.adoc index 840cae0479..bb6e6e293c 100644 --- a/modules/configuring/proc-provisioning-your-custom-configuration.adoc +++ b/modules/configuring/proc-provisioning-your-custom-configuration.adoc @@ -14,50 +14,48 @@ Your changes on this configuration might get reverted on {product-short} restart .Prerequisites * By using the {platform-cli-link}, you have access, with developer permissions, to the {platform-generic} cluster aimed at containing your {product-short} instance. +ifeval::["{context}" == "setting-up-and-configuring-your-first-rhdh-instance"] +include::snip-provisioning-your-custom-configuration-prerequisites-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc[] +endif::[] + .Procedure -. Author your custom `__.txt` file to provision your secrets as environment variables values in {a-platform-generic} secret, -rather than in clear text in your configuration files. -It contains one secret per line in `KEY=value` form. +. For security, store your secrets as environment variables values in an {ocp-short} secret, rather than in clear text in your configuration files. +Collect all your secrets in the `secrets.txt` file, with one secret per line in `KEY=value` form. + -* {authentication-book-link}[Enter your authentication secrets]. +-- +ifeval::["{context}" == "setting-up-and-configuring-your-first-rhdh-instance"] +include::snip-provisioning-your-custom-configuration-secrets-steps-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc[] +endif::[] +ifeval::["{context}" != "setting-up-and-configuring-your-first-rhdh-instance"] +include::snip-provisioning-your-custom-configuration-secrets-steps-in-default-context.adoc[] +endif::[] +-- . Author your custom `{my-app-config-file}` file. This is the main {product-short} configuration file. You need a custom `{my-app-config-file}` file to avoid the {product-short} installer to revert user edits during upgrades. When your custom `{my-app-config-file}` file is empty, {product-short} is using default values. ++ +-- +include::snip-provisioning-your-custom-configuration-appconfig-step-with-optional-steps-{optional-steps}d.adoc[] +-- -** To prepare a deployment with the {product} Operator on {platform}, you can start with an empty file. - -** To prepare a deployment with the {product} Helm chart, or on Kubernetes, enter the {product-short} base URL in the relevant fields in your `{my-app-config-file}` file to ensure proper functionality of {product-short}. -The base URL is what a {product-short} user sees in their browser when accessing {product-short}. -The relevant fields are `baseUrl` in the `app` and `backend` sections, and `origin` in the `backend.cors` subsection: +. Author your custom `dynamic-plugins.yaml` file to enable plugins. +By default, {product-short} enables a minimal plugin set, and disables plugins that require configuration or secrets, such as the GitHub repository discovery plugin and the Role-based access control (RBAC) plugin. + -.Configuring the `baseUrl` in `{my-app-config-file}` -==== -[source,yaml,subs="+attributes,+quotes"] +Enable the GitHub repository discovery and the RBAC features: ++ +.`dynamic.plugins.yaml` +[source,yaml] ---- -app: - title: {product} - baseUrl: {my-product-url} - -backend: - auth: - externalAccess: - - type: legacy - options: - subject: legacy-default-config - secret: "${BACKEND_SECRET}" - baseUrl: {my-product-url} - cors: - origin: {my-product-url} +includes: + - dynamic-plugins.default.yaml +plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github + disabled: false + - package: ./dynamic-plugins/dist/backstage-community-plugin-rbac + disabled: false ---- -==== - -** Optionally, enter your configuration such as: - -*** {authentication-book-link}[{authentication-book-title}]. -*** {authorization-book-link}[{authorization-book-title}]. -*** {customizing-book-link}[Customization]. . Provision your custom configuration files to your {platform} cluster. @@ -68,21 +66,30 @@ backend: $ oc create namespace {my-product-namespace} ---- -.. Provision your `{my-app-config-file}` file to the `{my-app-config-config-map}` config map in the _<{my-product-namespace}>_ project. +.. Provision your `{my-app-config-file}` and `dynamic-plugins.yaml` files respectively to the `{my-app-config-config-map}`, and `dynamic-plugins-rhdh` config maps in the _<{my-product-namespace}>_ project. + [source,terminal,subs="+attributes,+quotes"] ---- $ oc create configmap {my-app-config-config-map} --from-file={my-app-config-file} --namespace={my-product-namespace} +$ oc create configmap dynamic-plugins-rhdh --from-file=dynamic-plugins.yaml --namespace={my-product-namespace} ---- ++ +Alternatively, +link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nnodes-pods-configmap-create-from-console_configmaps[create the config maps by using the web console]. -.. Provision your `__.txt` file to the `__` secret in the _<{my-product-namespace}>_ project. +.. Provision your `secrets.txt` file to the `{my-product-secrets}` secret in the _<{my-product-namespace}>_ project. + [source,terminal,subs="+attributes,+quotes"] ---- -$ oc create secret generic `__` --from-file=`__.txt` --namespace={my-product-namespace} +$ oc create secret generic {my-product-secrets} --from-file=secrets.txt --namespace={my-product-namespace} ---- - -.Next steps -* To use an external PostgreSQL database, {configuring-book-link}configuring-external-postgresql-databases[provision your PostgreSQL database secrets]. -* To enable dynamic plugins, {installing-and-viewing-plugins-book-link}[provision your dynamic plugins config map]. -* To configure authorization by using external files, {authorization-book-link}#managing-authorizations-by-using-external-files[provision your RBAC policies config map]. ++ +Alternatively, +link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nodes-pods-secrets-creating-web-console-secrets_nodes-pods-secrets[create the secret by using the web console]. + +ifeval::["{context}" == "setting-up-and-configuring-your-first-rhdh-instance"] +include::snip-provisioning-your-custom-configuration-next-steps-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc[] +endif::[] +ifeval::["{context}" != "setting-up-and-configuring-your-first-rhdh-instance"] +include::snip-provisioning-your-custom-configuration-next-steps-in-default-context.adoc[] +endif::[] diff --git a/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration-in-getting-started-context.adoc b/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration-in-getting-started-context.adoc new file mode 100644 index 0000000000..c52da081be --- /dev/null +++ b/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration-in-getting-started-context.adoc @@ -0,0 +1,74 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_{context}"] +[id="using-the-operator-to-run-rhdh-with-your-custom-configuration"] += Using the {product} Operator to run {product-short} with your custom configuration + +Use the {product-short} Operator to run {product} with your custom configuration by creating your {product-custom-resource-type} custom resource (CR) that can perform the following actions: + +* Mount files provisioned in your custom config maps. +* Inject environment variables provisioned in your custom secrets. + +.Prerequisites +* By using the link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/cli_tools/index#cli-about-cli_cli-developer-commands[{openshift-cli}], you have access, with developer permissions, to the {ocp-short} cluster aimed at containing your {product-short} instance. +* xref:proc-install-operator_setting-up-and-configuring-your-first-rhdh-instance[] +* xref:provisioning-your-custom-configuration[] + +.Procedure + +. Author your {product-custom-resource-type} CR in a `{my-product-cr-name}.yaml` file to use your custom config maps and secrets. ++ +.`{my-product-cr-name}.yaml` custom resource example with dynamic plugins and RBAC policies config maps, and external PostgreSQL database secrets. +[source,yaml,subs="+attributes,+quotes"] +---- +apiVersion: rhdh.redhat.com/v1alpha3 +kind: Backstage +metadata: + name: _<{my-product-cr-name}>_ +spec: + application: + appConfig: + mountPath: /opt/app-root/src + configMaps: + - name: {my-app-config-config-map} + - name: rbac-policies + dynamicPluginsConfigMapName: dynamic-plugins-rhdh + extraEnvs: + envs: + - name: HTTP_PROXY + value: 'http://10.10.10.105:3128' + - name: HTTPS_PROXY + value: 'http://10.10.10.106:3128' + - name: NO_PROXY + value: 'localhost,example.org' + secrets: + - name: {my-product-secrets} + extraFiles: + mountPath: /opt/app-root/src + secrets: + - name: {my-product-database-certificates-secrets} + key: postgres-crt.pem, postgres-ca.pem, postgres-key.key + replicas: 2 + database: + enableLocalDb: false +---- + +`application`:: +`appConfig`::: Register your `{my-app-config-config-map}` and `rbac-policies` config maps. +`dynamicPluginsConfigMapName`::: Register your `dynamic-plugins-rhdh` config map. +`extraEnvs`::: +`env`:::: Enter your proxy environment variables. +`secrets`:::: Register your `` and `{my-product-database-secrets}` secrets. +`extraFiles`::: +`secrets`:::: +Register the `postgres-crt.pem`, `postgres-ca.pem`, and `postgres-key.key` files contained in the `{my-product-database-certificates-secrets}` secret. +`replicas`::: Enable high availability (HA) by increasing the replicas count to a value higher or equal to 2. +`database`:: +`enableLocalDb`::: Use your external PostgreSQL database rather than the internal PostgreSQL database. + +. Apply your {product-custom-resource-type} CR to start or update your {product-short} instance. ++ +[source,terminal,subs="+attributes,+quotes"] +---- +$ oc apply --filename={my-product-cr-name}.yaml --namespace={my-product-namespace} +---- diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-with-optional-steps-disabled.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-with-optional-steps-disabled.adoc new file mode 100644 index 0000000000..5f68885c65 --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-with-optional-steps-disabled.adoc @@ -0,0 +1,70 @@ +.. For a production environment, start with the following setup: ++ +.`{my-app-config-file}` +[source,yaml,subs="+attributes,+quotes"] +---- +app: + title: _<{product}>_ + branding: + fullLogo: ${BASE64_EMBEDDED_FULL_LOGO} + fullLogoWidth: 110px + iconLogo: ${BASE64_EMBEDDED_ICON_LOGO} +backend: + cache: + store: redis + connection: ${REDIS_CONNECTION} +techdocs: + cache: + ttl: 3600000 +catalog: + providers: + github: + providerId: + organization: "${GITHUB_INTEGRATION_ORGANIZATION}" + schedule: + frequency: + minutes: 30 + initialDelay: + seconds: 15 + timeout: + minutes: 15 +integrations: + github: + - host: ${GITHUB_INTEGRATION_HOST_DOMAIN} + apps: + - appId: ${GITHUB_INTEGRATION_APP_ID} + clientId: ${GITHUB_INTEGRATION_CLIENT_ID} + clientSecret: ${GITHUB_INTEGRATION_CLIENT_SECRET} + privateKey: | + ${GITHUB_INTEGRATION_PRIVATE_KEY_FILE} +permission: + enabled: true + rbac: + admin: + users: + - name: user:default/ + pluginsWithPermission: + - catalog + - scaffolder + - permission +---- +Most fields use environment variables that you defined in secrets in the previous step. +`app`:: +`title`::: Enter your Developer Hub instance display name, such as _<{product}>_. +`branding`::: Set your custom logo. ++ +Optionally, customize the width of the branding logo by changing value for the `fullLogoWidth` field. The following units are supported: integer, px, em, rem, percentage. +`backend`:: +`cache`::: Enable the plugins assets cache. +`techdocs`:: +`cache`::: Enable the Techdocs cache. +`catalog`:: +`provider`::: +`github`:::: Enable GitHub repository discovery. +`integrations`:: +`github`::: Enable GitHub repository discovery. +[id='enabling-and-giving-access-to-rbac'] +`permissions`:: Enable Role-based access control. +Enter your policy administrator name. + +.. Additionally, link:{authentication-book-url}[provision users and enable authentication with your external identity provider]. diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-with-optional-steps-enabled.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-with-optional-steps-enabled.adoc new file mode 100644 index 0000000000..1b831511ae --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-with-optional-steps-enabled.adoc @@ -0,0 +1,35 @@ + +** To prepare a deployment with the {product} Operator on {ocp-short}, you can start with an empty file. + +** To prepare a deployment with the {product} Helm chart, or on Kubernetes, enter the {product-short} base URL in the relevant fields in your `{my-app-config-file}` file to ensure proper functionality of {product-short}. +The base URL is what a {product-short} user sees in their browser when accessing {product-short}. +The relevant fields are `baseUrl` in the `app` and `backend` sections, and `origin` in the `backend.cors` subsection: ++ +.Configuring the `baseUrl` in `{my-app-config-file}` +==== +[source,yaml,subs="+attributes,+quotes"] +---- +app: + title: {product} + baseUrl: {my-product-url} + +backend: + auth: + externalAccess: + - type: legacy + options: + subject: legacy-default-config + secret: "${BACKEND_SECRET}" + baseUrl: {my-product-url} + cors: + origin: {my-product-url} +---- +==== + +** Optionally, enter your configuration such as: + +*** {authentication-book-link}[{authentication-book-title}]. +*** {authorization-book-link}[{authorization-book-title}]. +*** {customizing-book-link}[Customization]. +*** {customizing-book-link}#configuring-an-rhdh-instance-with-tls-in-kubernetes_{context}[Configure your {ocp-short} integration]. + diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-default-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-default-context.adoc new file mode 100644 index 0000000000..70d2ef9f02 --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-default-context.adoc @@ -0,0 +1,4 @@ +.Next steps +* {configuring-book-link}#configuring-external-postgresql-databases[Provision your PostgreSQL database secrets] +* {installing-and-viewing-plugins-book-link}[Provision your dynamic plugins config map] +* {authorization-book-link}#managing-authorizations-by-using-external-files[Provision your RBAC policies config map] diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc new file mode 100644 index 0000000000..89784779c0 --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc @@ -0,0 +1,6 @@ +.. Provision your PosgreSQL TLS certificates to the `{my-product-database-secrets}` secret in the _<{my-product-namespace}>_ project. ++ +[source,terminal,subs="+attributes,+quotes"] +---- +$ oc create secret generic {my-product-secrets} --from-file=postgres-ca.pem --from-file=postgres-crt.pem --from-file=postgres-key.key --namespace={my-product-namespace} +---- diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-prerequisites-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-prerequisites-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc new file mode 100644 index 0000000000..648517c8fd --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-prerequisites-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc @@ -0,0 +1,25 @@ +* You have the connection string to an active Redis server, such as `rediss://user:pass@cache.example.com:6379`. +For security, consider using a `rediss` secure server connection. +See xref:preparing-your-external-services[]. +* You have an external PostgreSQL database, with the following details. +See See xref:preparing-your-external-services[]. + +postgres-host::: Your PostgreSQL instance Domain Name System (DNS) or IP address. +postgres-port::: Your PostgreSQL instance port number, such as 5432. +postres-username::: The user name to connect to your PostgreSQL instance. +postgres-password::: The password to connect to your PostgreSQL instance. +postgres-ca.pem::: +postgres-key.key::: +postgres-crt.pem::: +TLS certificates to secure the connection to the database. + +* You have a GitHub App enabling access to the GitHub API for repository discovery, with the following details. +See xref:preparing-your-external-services[]. +GITHUB_INTEGRATION_APP_ID::: +Your GitHub integration App ID. +GITHUB_INTEGRATION_CLIENT_ID::: +Your GitHub integration App client ID. +GITHUB_INTEGRATION_CLIENT_SECRET::: +Your GitHub integration App client secret. +GITHUB_INTEGRATION_PRIVATE_KEY_FILE::: +Your GitHub integration App private key. diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-secrets-steps-in-default-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-secrets-steps-in-default-context.adoc new file mode 100644 index 0000000000..e7b8175dbb --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-secrets-steps-in-default-context.adoc @@ -0,0 +1 @@ +* {authentication-book-link}[Enter your authentication secrets]. diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-secrets-steps-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-secrets-steps-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc new file mode 100644 index 0000000000..3e9835fd3d --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-secrets-steps-in-setting-up-and-configuring-your-first-rhdh-instance-context.adoc @@ -0,0 +1,53 @@ +.. Enter your custom logo. ++ +[source,subs="+attributes,+quotes"] +---- +BASE64_EMBEDDED_FULL_LOGO="data:image/svg+xml;base64," +BASE64_EMBEDDED_ICON_LOGO="data:image/svg+xml;base64," +---- + +`BASE64_EMBEDDED_FULL_LOGO`:: +Enter your logo for the expanded (pinned) sidebar as a base64 encoded SVG image. ++ +To encode your logo in base64, run: ++ +[source] +---- +$ base64 -i logo.svg +---- + +`BASE64_EMBEDDED_ICON_LOGO`:: +Enter your logo for the collapsed (unpinned) sidebar as a base64 encoded SVG image. + +.. Enter the connection string to your Redis server that caches plugin assets. ++ +[source] +---- +REDIS_CONNECTION=rediss://user:pass@cache.example.com:6379 +---- + +.. Enter your GitHub integration credentials: ++ +[source,subs="+quotes"] +---- +GITHUB_INTEGRATION_APP_ID=___ +GITHUB_INTEGRATION_CLIENT_ID=__ +GITHUB_INTEGRATION_CLIENT_SECRET=__ +GITHUB_INTEGRATION_HOST_DOMAIN=github.com +GITHUB_INTEGRATION_ORGANIZATION=__ +GITHUB_INTEGRATION_PRIVATE_KEY_FILE= __ +---- + +.. Enter your PosgreSQL database secrets: ++ +[source,subs="+quotes"] +---- +POSTGRES_PASSWORD: +POSTGRES_PORT: "" +POSTGRES_USER: +POSTGRES_HOST: +PGSSLMODE: verify-full +NODE_EXTRA_CA_CERTS: /opt/app-root/src/postgres-crt.pem +---- + +.. {authentication-book-link}[Enter your authentication secrets]. diff --git a/modules/customizing-templates/proc-enabling-software-template-version-update-notifications.adoc b/modules/customizing-templates/proc-enabling-software-template-version-update-notifications.adoc new file mode 100644 index 0000000000..023e046e25 --- /dev/null +++ b/modules/customizing-templates/proc-enabling-software-template-version-update-notifications.adoc @@ -0,0 +1,73 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-enabling-software-template-version-update-notifications_{context}"] += Enabling Software Template version update notifications in {product} + +As a platform engineer, you can enable notification alerts for template version updates using the `@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor` module, an extension to the `catalog-backend` plugin. When enabled, this module automatically notifies component owners whenever the Software Template used to generate their components is updated to a new version. + +This functionality uses the `spec.scaffoldedFrom` field in catalog entities. This field links Software Templates to the entities they have scaffolded. By tracking this relationship, the module helps teams stay informed and take advantage of the latest improvements or fixes. + +The `plugin-catalog-backend-module-scaffolder-relation-processor` module is disabled by default. + + +.Prerequisites + +* You have installed and configured the Backstage backend notification plugin `@backstage/plugin-notifications-backend`. +* You have installed and configured the Backstage frontend plugin `@backstage/plugin-notifications`. + + +.Procedure + +. To enable the notifications, in your `{product} app-config.yaml` file, add the following codes: +.. In the `dynamicPlugins:frontend` section: ++ +[source,yaml] +---- +frontend: + backstage.plugin-notifications: + dynamicRoutes: + - importName: NotificationPage + menuItem: + config: + props: + titleCounterEnabled: true + webNotificationsEnabled: false + importName: NotificationsSidebarItem + path: /notifications +---- +.. In a new section: ++ +[source,yaml] +---- +scaffolder: + notifications: + templateUpdate: + enabled: true # Set to false to disable notifications +---- +You can also customize the notification title and description as shown in the following code: ++ +[source,yaml] +---- +scaffolder: + notifications: + templateUpdate: + enabled: true + message: + title: 'Custom title for $ENTITY_DISPLAY_NAME' + description: 'Custom description' +---- ++ +where: + +`enabled`:: Set to `true` to enable the notification. Default value is `false`. +`message:title`:: Enter the notification title. +`message:description`:: Enter the notification description. + +[NOTE] +==== +Both `message:title` and `message:description` support the template variable `$ENTITY_DISPLAY_NAME`. The system automatically substitutes this variable with the title (or the name, if the title is missing) of the entity scaffolded from the updated template. +==== + +.Verification +* In your {product} instance, on the left navigation menu, you are able to see `Notifications`, or, if configured, the custom title. +* When you update the version number in the Software Template, you receive a notification. \ No newline at end of file diff --git a/modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc b/modules/customizing-the-appearance/con-about-rhdh-sidebar-menuitems.adoc similarity index 81% rename from modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc rename to modules/customizing-the-appearance/con-about-rhdh-sidebar-menuitems.adoc index fc1b5c8e8d..6b60ba8d8e 100644 --- a/modules/customizing-the-appearance/con-customize-rhdh-sidebar-menuitems.adoc +++ b/modules/customizing-the-appearance/con-about-rhdh-sidebar-menuitems.adoc @@ -1,7 +1,7 @@ :_mod-docs-content-type: CONCEPT -[id="con-customize-rhdh-sidebar-menuitems_{context}"] -= Customizing the sidebar menu items for your {product-short} instance +[id="con-about-rhdh-sidebar-menuitems_{context}"] += About the sidebar menu items for your {product-short} instance The sidebar menu in {product} consists of two main parts that you can configure: diff --git a/modules/customizing-the-appearance/con-language-persistence.adoc b/modules/customizing-the-appearance/con-language-persistence.adoc new file mode 100644 index 0000000000..8087ff8fc2 --- /dev/null +++ b/modules/customizing-the-appearance/con-language-persistence.adoc @@ -0,0 +1,23 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-language-persistence_{context}"] += Language persistence + +When you change the language in the UI, your preference is saved to storage. On next login or refresh, your chosen language setting is restored. Guest users cannot persist language preferences. + +Default language selection uses the following priority order: + +. *Browser language priority*: The system first checks the user's browser language preferences to provide a personalized experience. + +. *Configuration priority*: If no browser language matches the supported locales, the `defaultLocale` from the `i18n` configuration is used as a fallback. + +. *Fallback priority*: If neither browser preferences nor configuration provide a match, defaults to `en`. + +Red Hat Developer Hub automatically saves and restores user language settings across browser sessions. This feature is enabled by default and uses database storage. To opt-out and use browser storage instead, add the following to your `app-config.yaml`: +[source,yaml,subs="+quotes"] +---- +userSettings: + persistence: browser # <1> +---- +<1> To opt-out and use browser local storage, set this value to `browser`. Optionally, set this value to `database` to persist across browsers and devices. This the default setting and does not require this configuration to be set. + diff --git a/modules/customizing-the-appearance/proc-adding-localization-to-custom-plugins.adoc b/modules/customizing-the-appearance/proc-adding-localization-to-custom-plugins.adoc new file mode 100644 index 0000000000..04b505e1b4 --- /dev/null +++ b/modules/customizing-the-appearance/proc-adding-localization-to-custom-plugins.adoc @@ -0,0 +1,301 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-adding-localization-to-custom-plugins_{context}"] += Adding localization to custom plugins +You can implement localization support in your custom Red Hat Developer Hub plugins so that your plugins are accessible to a diverse, international user base and follow recommended best practices. + +.Procedure +. Create the following translation files in your plugin's `src/translations/ directory`: ++ +.`src/translations/ref.ts` English language reference +[source,json] +---- +src/translations/ref.ts - English Reference +import { createTranslationRef } from "@backstage/core-plugin-api/alpha"; + + +export const myPluginMessages = { + page: { + title: "My Plugin", + subtitle: "Plugin description", + }, + common: { + exportCSV: "Export CSV", + noResults: "No results found", + }, + table: { + headers: { + name: "Name", + count: "Count", + }, + }, +}; + + +export const myPluginTranslationRef = createTranslationRef({ + id: "plugin.my-plugin", + messages: myPluginMessages, +}); +---- + ++ +.`src/translations/de.ts` German language reference +[source,json] +---- +import { createTranslationMessages } from "@backstage/core-plugin-api/alpha"; +import { myPluginTranslationRef } from "./ref"; + + +const myPluginTranslationDe = createTranslationMessages({ + ref: myPluginTranslationRef, + messages: { + "page.title": "Mein Plugin", + "page.subtitle": "Plugin-Beschreibung", + "common.exportCSV": "CSV exportieren", + "common.noResults": "Keine Ergebnisse gefunden", + "table.headers.name": "Name", + "table.headers.count": "Anzahl", + }, +}); + + +export default myPluginTranslationDe; +---- + ++ +.`src/translations/fr.ts` French language reference +[source,json] +---- +import { createTranslationMessages } from "@backstage/core-plugin-api/alpha"; +import { myPluginTranslationRef } from "./ref"; + + +const myPluginTranslationFr = createTranslationMessages({ + ref: myPluginTranslationRef, + messages: { + "page.title": "Mon Plugin", + "page.subtitle": "Description du plugin", + "common.exportCSV": "Exporter CSV", + "common.noResults": "Aucun résultat trouvé", + "table.headers.name": "Nom", + "table.headers.count": "Nombre", + }, +}); + + +export default myPluginTranslationFr; +---- + ++ +.`src/translations/index.ts` translation resource +[source,json] +---- +import { createTranslationResource } from "@backstage/core-plugin-api/alpha"; +import { myPluginTranslationRef } from "./ref"; + + +export const myPluginTranslations = createTranslationResource({ + ref: myPluginTranslationRef, + translations: { + de: () => import("./de"), + fr: () => import("./fr"), + }, +}); + + +export { myPluginTranslationRef }; +---- + +. Create translation hooks ++ +.`src/hooks/useTranslation.ts` translation hooks +[source,json] +---- +src/hooks/useTranslation.ts +import { useTranslationRef } from "@backstage/core-plugin-api/alpha"; +import { myPluginTranslationRef } from "../translations"; + + +export const useTranslation = () => useTranslationRef(myPluginTranslationRef); +---- + +. Update your plugin components to replace hardcoded strings with translation calls: ++ +.Before (hardcoded): +[source,json] +---- +const MyComponent = () => { + return ( +
+

My Plugin

+ +
+ ); +}; +---- ++ +.After (translated): +[source,json] +---- +import { useTranslation } from '../hooks/useTranslation'; + + +const MyComponent = () => { + const { t } = useTranslation(); + + + return ( +
+

{t('page.title')}

+ +
+ ); +}; +---- + +. (Optional) For content with variables, use interpolation: ++ +[source,json] +---- +// In your translation files +'table.pagination.topN': 'Top {{count}} items' +---- + ++ +[source,json] +---- +// In your component +const { t } = useTranslation(); +const message = t('table.pagination.topN', { count: '10' }); +For dynamic translation keys (e.g., from configuration): +// Configuration object with translation keys +const CARD_CONFIGS = [ + { id: 'overview', titleKey: 'cards.overview.title' }, + { id: 'details', titleKey: 'cards.details.title' }, + { id: 'settings', titleKey: 'cards.settings.title' }, +]; + + +// In your component +const { t } = useTranslation(); + + +const CardComponent = ({ config }) => { + return ( +
+

{t(config.titleKey as any)}

+ {/* Use 'as any' for dynamic keys */} +
+ ); +}; +---- + + +. Export translation resources ++ +[source,json] +---- +In your plugin's src/index.ts: +// Export your plugin +export { myPlugin } from "./plugin"; + + +// Export translation resources for RHDH +export { myPluginTranslations, myPluginTranslationRef } from "./translations"; +6. Configure in RHDH +For RHDH (dynamic plugins configuration): +Add to your dynamic-plugins.default.yaml: + +backstage-community.plugin-my-plugin: + translationResources: + - importName: myPluginTranslations + ref: myPluginTranslationRef +For local Backstage app development: +// In your app's App.tsx +import { myPluginTranslations } from "@my-org/backstage-plugin-my-plugin"; + + +const app = createApp({ + apis, + __experimentalTranslations: { + availableLanguages: ["en", "de", "fr"], + resources: [myPluginTranslations], + }, +}); +---- + +. Testing Your Translations ++ +[source,json] +---- +Create test mocks (src/test-utils/mockTranslations.ts): +import { myPluginMessages } from "../translations/ref"; + + +function flattenMessages(obj: any, prefix = ""): Record { + const flattened: Record = {}; + for (const key in obj) { + if (obj.hasOwnProperty(key)) { + const value = obj[key]; + const newKey = prefix ? `${prefix}.${key}` : key; + if (typeof value === "object" && value !== null) { + Object.assign(flattened, flattenMessages(value, newKey)); + } else { + flattened[newKey] = value; + } + } + } + return flattened; +} + + +const flattenedMessages = flattenMessages(myPluginMessages); + + +export const mockT = (key: string, params?: any) => { + let message = flattenedMessages[key] || key; + if (params) { + for (const [paramKey, paramValue] of Object.entries(params)) { + message = message.replace( + new RegExp(`{{${paramKey}}}`, "g"), + String(paramValue), + ); + } + } + return message; +}; + + +export const mockUseTranslation = () => ({ t: mockT }); +Update your tests: +import { mockUseTranslation } from "../test-utils/mockTranslations"; + + +jest.mock("../hooks/useTranslation", () => ({ + useTranslation: mockUseTranslation, +})); +---- + +// Your test code... +== Best practices +* Never modify original English strings - Keep them exactly as they were +* Use flat dot notation in translation files (e.g., 'page.title') +* Use nested objects in the reference file for TypeScript support +* Test with mocks to ensure translations work correctly +* Add all languages to your app configuration + +== Common Patterns +Use Case Pattern Example +Simple text t('key') t('page.title') +With variables t('key', {param}) t('table.topN', {count: '5'}) +Dynamic keys t(config.titleKey as any) t('cards.overview.title' as any) + +== Validation Checklist +* All hardcoded strings replaced with translation calls +* Translation files created for all target languages +* Translation resources exported from src/index.ts +* For RHDH: Dynamic plugins configuration updated with translationResources +* For local app: App configuration updated with available languages +* Tests updated with translation mocks +* Language switching works in the UI +* Fallback to English works for missing translations \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc b/modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc index 8302eba848..b0005308fd 100644 --- a/modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc +++ b/modules/customizing-the-appearance/proc-configuring-dynamic-plugin-menuitem.adoc @@ -13,30 +13,43 @@ Configure a dynamic plugin menu item using the following step: ---- dynamicPlugins: frontend: - __: # <1> + __: menuItems: - : # <2> - icon: # home | group | category | extension | school | __ # <3> - title: __ # <4> - priority: 10 # <5> - parent: favorites # <6> - enabled: true # <7> + : + icon: # home | group | category | extension | school | __ + title: __ + priority: 10 + parent: favorites + enabled: true ---- -<1> `__`: Enter the plugin name. This name is the same as the `scalprum.name` key in the `package.json` file. -<2> `__`: Enter a unique name in the main sidebar navigation for either a standalone menu item or a parent menu item. If this field specifies a plugin menu item, the name of the menu item must match the name using in the corresponding path in `dynamicRoutes`. For example, if `dynamicRoutes` defines `path: /my-plugin`, then `menu_item_name` must be defined as `my-plugin`. -<3> `icon`: (Optional) Enter the icon name. You can use any of the following icons: +`__`:: +Enter the plugin name. This name is the same as the `scalprum.name` key in the `package.json` file. + +`__`:: +Enter a unique name in the main sidebar navigation for either a standalone menu item or a parent menu item. If this field specifies a plugin menu item, the name of the menu item must match the name using in the corresponding path in `dynamicRoutes`. For example, if `dynamicRoutes` defines `path: /my-plugin`, then `menu_item_name` must be defined as `my-plugin`. + +`icon`:: +(Optional) Enter the icon name. You can use any of the following icons: ** Default icons, such as `home`, `group`, `category`, `extension`, and `school`. To use default icons, set the icon as an (`" "`) empty string. ** A custom icon, where __ specifies the name of your custom icon ** An SVG icon, such as: `icon: ...` ** An HTML image, such as: `icon: https://img.icons8.com/ios-glyphs/20/FFFFFF/shop.png` -<4> `title`: (Optional) Enter the menu item title. Omit it when the title is already specified in the `dynamicRoutes` configuration under `menuItem.text`. To hide the title from the sidebar, set the title as an (`" "`) empty string. + +`title`:: +(Optional) Enter the menu item title. Omit it when the title is already specified in the `dynamicRoutes` configuration under `menuItem.text`. To hide the title from the sidebar, set the title as an (`" "`) empty string. // Update <4> for release 1.6 as this option (currently a workaround) would be added as a functionality. RHIDP-6333. -<5> `priority`: (Optional) Sets the order in which menu items appear in the sidebar. The default priority is 0, which places the item at the bottom of the list. A higher priority value places the item higher in the sidebar. You can define this field for each section. -<6> `parent`: (Optional) Enter the parent menu item under which the current item is nested. If this field is used, the parent menu item must be defined elsewhere in the `menuItems` configuration of any enabled plugin. You can define this field for each section. -<7> `enabled`: (Optional) If this field is used to hide the menu item from the sidebar, set the value to `false`. To display the menu item in the sidebar, set the value to `true`. + +`priority`:: +(Optional) Enter an integer value to set the order in which menu items appear in the sidebar. + +`parent`:: +(Optional) Enter the parent menu item under which the current item is nested. If this field is used, the parent menu item must be defined elsewhere in the `menuItems` configuration of any enabled plugin. You can define this field for each section. + +`enabled`:: +(Optional) Enter `false` to hide the menu item from the sidebar. +Enter `true` to display the menu item in the sidebar. + -.Example `menuItems` configuration [source,yaml,subs="+attributes"] ---- dynamicPlugins: @@ -50,18 +63,25 @@ dynamicPlugins: icon: fooIcon text: Foo Plugin Page menuItems: - my-plugin: # <1> - priority: 10 # <2> - parent: favorites # <3> - favorites: # <4> - icon: favorite # <5> - title: Favorites # <6> - priority: 100 # <7> + my-plugin: + priority: 10 + parent: favorites + favorites: + icon: favorite + title: Favorites + priority: 100 ---- -<1> `my-plugin`: Matches the value of the `path` field in `dynamicRoutes`. -<2> `priority`: Controls order of plugins under the parent menu item. -<3> `parent`: Nests this plugin under the `favorites` parent menu item. -<4> `favorites`: Configuration for the parent menu item. -<5> `icon`: Displays the `favorite` icon from the {product-very-short} system icons. -<6> `title`: Displays the title name for the parent menu item. -<7> `priority`: Order of the `favourites` menu item in the sidebar. +`my-plugin`:: +Enter the value of the `path` field in `dynamicRoutes`. + +`priority`:: +Enter an integer value to set the order in which plugins appear in the parent menu item. + +`parent`:: +Enter the parent menu item id to nest this plugin under, such as `favorites`. + +`favorites`:: +Configuration for the parent menu item. + +`title`:: +Displays the title name for the parent menu item. \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc b/modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc index ff48955707..ff6f61e507 100644 --- a/modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc +++ b/modules/customizing-the-appearance/proc-customize-rhdh-branding-logo.adoc @@ -12,11 +12,8 @@ app: fullLogo: ${BASE64_EMBEDDED_FULL_LOGO} <1> iconLogo: ${BASE64_EMBEDDED_ICON_LOGO} <2> ---- - -where: - -<1> `fullLogo` is the logo on the expanded (pinned) sidebar and expects a base64 encoded image. -<2> `iconLogo` is the logo on the collapsed (unpinned) sidebar and expects a base64 encoded image. +`fullLogo`:: Enter the logo on the expanded (pinned) sidebar as a base64 encoded image. +`iconLogo`:: Enter the logo on the collapsed (unpinned) sidebar as a base64 encoded image. + You can format the `BASE64_EMBEDDED_FULL_LOGO` environment variable as follows: + @@ -40,9 +37,7 @@ You can also customize the width of the branding logo by setting a value for the ---- app: branding: - fullLogoWidth: 110px <1> + fullLogoWidth: 110px # ... ---- - -<1> The default value for the logo width is `110px`. The following units are supported: `integer`, `px`, `em`, `rem`, percentage. - +`fullLogoWidth`:: The default value for the logo width is `110px`. The following units are supported: `integer`, `px`, `em`, `rem`, percentage. \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-customize-rhdh-language.adoc b/modules/customizing-the-appearance/proc-customize-rhdh-language.adoc new file mode 100644 index 0000000000..c0df299ad7 --- /dev/null +++ b/modules/customizing-the-appearance/proc-customize-rhdh-language.adoc @@ -0,0 +1,28 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-customize-rhdh-language_{context}"] += Customizing the language for your {product-short} instance + +The language settings of {product-very-short} use English by default. You can choose to use one of the following languages instead. + +.Supported languages +* English +* French + +The default language is English, which automatically sets the light or dark theme based on your system preferences. + +[NOTE] +==== +English and French are the supported languages in {product-very-short} 1.8. You can add other languages in the the `i18n` section of your `{my-app-config-file}` configuration file. +==== + +.Prerequisites + +* You are logged in to the {product-short} web console. + +.Procedure + +. From the {product-short} web console, click *Settings*. +. From the *Appearance* panel, click the language dropdown to select your language of choice. ++ +image::rhdh/customize-language-dropdown.png[] \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-customize-rhdh-page-theme.adoc b/modules/customizing-the-appearance/proc-customize-rhdh-page-theme.adoc index 9ceff8964e..1d2dd9016d 100644 --- a/modules/customizing-the-appearance/proc-customize-rhdh-page-theme.adoc +++ b/modules/customizing-the-appearance/proc-customize-rhdh-page-theme.adoc @@ -10,14 +10,14 @@ You can customize the header color for the light and dark theme modes in your {p app: branding: theme: - light: <1> + light: palette: {} pageTheme: - default: <2> - backgroundColor: "" <3> - fontColor: "" <4> - shape: none <5> - apis: <6> + default: + backgroundColor: "" + fontColor: "" + shape: none + apis: backgroundColor: "" fontColor: "" shape: none @@ -30,13 +30,12 @@ app: shape: none # ... ---- - -<1> The theme mode, for example, `light` or `dark` -<2> The `yaml` header for the default page theme configuration -<3> The color of the page header background, for example, `#ffffff` or `white` -<4> The color of the text in the page header, for example, `#000000` or `black` -<5> The pattern on the page header, for example, `wave`, `round`, or `none` -<6> The `yaml` header for a specific page theme configuration, for example, `apis`, `home` +`light`:: Enter the theme mode, such as `light` or `dark`. +`default`:: Enter the default page theme configuration +`backgroundColor`::: Enter the page header background color, such as `#ffffff` or `white`. +`fontColor`::: Enter the page header text color, such as `#000000` or `black`. +`shape`::: Enter the page header pattern, such as `wave`, `round`, or `none`. +`apis::` Enter the page id to configure, such as `apis` or `home`. //The page theme name depends on the plugin that you are customizing the page header for. //can include information about this topic in the future. diff --git a/modules/customizing-the-appearance/proc-customize-rhdh-palette.adoc b/modules/customizing-the-appearance/proc-customize-rhdh-palette.adoc index 94214bfdd8..f268ccbfd6 100644 --- a/modules/customizing-the-appearance/proc-customize-rhdh-palette.adoc +++ b/modules/customizing-the-appearance/proc-customize-rhdh-palette.adoc @@ -13,30 +13,27 @@ app: light: palette: primary: - main: <1> + main: navigation: - indicator: <2> + indicator: pageTheme: default: - backgroundColor: [, ] <3> + backgroundColor: [, ] dark: palette: primary: - main: <4> + main: navigation: - indicator: <5> + indicator: pageTheme: default: - backgroundColor: [, ] <6> + backgroundColor: [, ] # ... ---- - -<1> The main primary color for the light color palette, for example, `#ffffff` or `white` -<2> The color of the navigation indicator for the light color palette, which is a vertical bar that indicates the selected tab in the navigation panel, for example, `#FF0000` or `red` -<3> The background color for the default page theme for the light color palette, for example, `#ffffff` or `white` -<4> The main primary color for the dark color palette, for example, `#000000` or `black` -<5> The color of the navigation indicator for the dark color palette, which is a vertical bar that indicates the selected tab in the navigation panel, for example, `#FF0000` or `red` -<6> The background color for the default page theme for the dark color palette, for example, `#000000` or `black` +`light|dark`:: Enter the theme name: `light` or `dark`. +`palette.primary:main`::: Enter the palette main primary color, such as `#ffffff` or `white`. +`palette.navigation:indicator`::: Enter the palette navigation indicator color, which is a vertical bar that indicates the selected tab in the navigation panel, such as `#FF0000` or `red`. +`pageTheme:default:backgroundColor`::: Enter the default page theme background color, such as `#ffffff` or `white`. .Additional resources * xref:proc-customizing-rhdh-theme-mode_{context}[] diff --git a/modules/customizing-the-appearance/proc-customize-rhdh-theme-mode.adoc b/modules/customizing-the-appearance/proc-customize-rhdh-theme-mode.adoc index 568caf4b9f..9b8cebd1b4 100644 --- a/modules/customizing-the-appearance/proc-customize-rhdh-theme-mode.adoc +++ b/modules/customizing-the-appearance/proc-customize-rhdh-theme-mode.adoc @@ -3,18 +3,18 @@ [id="proc-customizing-rhdh-theme-mode_{context}"] = Customizing the theme mode for your {product-short} instance +You can choose one of the following theme modes for your {product-short} instance: + +* *Light* +* *Dark* +* *Auto* + [NOTE] ==== In {product-short}, theme configurations are used to change the look and feel of different UI components. So, you might notice changes in different UI components, such as buttons, tabs, sidebars, cards, and tables along with some changes in background color and font used on the {product-very-short} pages. ==== -You can choose one of the following theme modes for your {product-short} instance: - -* Light theme -* Dark theme -* Auto - -The default theme mode is Auto, which automatically sets the light or dark theme based on your system preferences. +The default theme mode is *Auto*, which automatically sets the light or dark theme based on your system preferences. .Prerequisites @@ -23,7 +23,7 @@ The default theme mode is Auto, which automatically sets the light or dark theme .Procedure . From the {product-short} web console, click *Settings*. -. From the *Appearance* panel, click *LIGHT THEME*, *DARK THEME*, or *AUTO* to change the theme mode. +. From the *Appearance* panel, click *Light*, *Dark*, or *Auto* to change the theme mode. + image::user-guide/custom-theme-mode-1.png[] diff --git a/modules/customizing-the-appearance/proc-enabling-localization-in-rhdh.adoc b/modules/customizing-the-appearance/proc-enabling-localization-in-rhdh.adoc new file mode 100644 index 0000000000..5be7cc5254 --- /dev/null +++ b/modules/customizing-the-appearance/proc-enabling-localization-in-rhdh.adoc @@ -0,0 +1,26 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-enabling-localization-in-rhdh_{context}"] += Enabling the localization framework in {product-short} +Enabling localization enhances accessibility, improves the user experience for a global audience, and assists organizations in meeting language requirements in specific regions. + +The language settings of {product-very-short} use English by default. In {product-very-short} {product-version}, you can choose to use one of the following supported languages: + +* English (en) +* French (fr) + +.Prerequisites + +.Procedure +. To enable the localization framework in your {product-very-short} application, add the `i18n` section to your custom {product-short} `{my-app-config-file}` configuration file: ++ +[id=i18n] +.`{my-app-config-file}` fragment with localization `i18n` fields +[source,yaml,subs="+quotes"] +---- +i18n: + locales: # List of supported locales. Must include `en`, otherwise the translation framework will fail to load. + - en + - fr + defaultLocale: en # Optional. Defaults to `en` if not specified. +---- \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-loading-custom-theme-using-dynamic-plugin.adoc b/modules/customizing-the-appearance/proc-loading-custom-theme-using-dynamic-plugin.adoc index a373d9ead1..d7ffb80fc7 100644 --- a/modules/customizing-the-appearance/proc-loading-custom-theme-using-dynamic-plugin.adoc +++ b/modules/customizing-the-appearance/proc-loading-custom-theme-using-dynamic-plugin.adoc @@ -30,13 +30,15 @@ dynamicPlugins: frontend: example.my-custom-theme-plugin: themes: - - id: light # <1> + - id: light title: Light variant: light icon: someIconReference importName: lightThemeProvider ---- -<1> Set your theme ID by specifying the desired value. Optionally, override the default {product-short} themes by using the following ID values: `light` to replace the default light theme, or `dark` to replace the default dark theme. +`id`:: Enter your theme ID, such as `my_theme`. +Enter `dark` to override the default {product-short} dark theme. +Enter `light` to override the default {product-short} light theme. .Verification diff --git a/modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc b/modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc index dc67acbac9..e376098969 100644 --- a/modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc +++ b/modules/customizing-the-appearance/proc-modifying-or-adding-rhdh-custom-menuitem.adoc @@ -14,59 +14,58 @@ dynamicPlugins: frontend: default.main-menu-items: menuItems: - default.__: # <1> - icon: # home | group | category | extension | school | __ # <2> - title: __ # <3> - priority: 10 # <4> - default.__: # <5> - parent: __ # <6> - icon: # home | group | category | extension | school | __ # <7> - title: __ # <8> - to: __ # <9> - priority: 100 # <10> - enabled: true # <11> + default.__: + icon: # home | group | category | extension | school | __ + title: __ + priority: 10 + default.__: + parent: __ + icon: # home | group | category | extension | school | __ + title: __ + to: __ + priority: 100 + enabled: true ---- -<1> `default.__`: (Optional) Enter the menu group parent item name to configure static main menu items. If no `default.__` has a `parent` value set, this field is not needed. -<2> `icon`: Enter the menu icon. Required for parent menu items. -<3> `title`: Enter the menu group title. Required for parent menu items. -<4> `priority`: (Optional) Enter the order of this menu item within its menu level. -<5> `default.__`: Enter the menu item name for which you want to override the default value. Add the `default.` prefix to identify a main menu item. -<6> `parent`: (Optional) Enter the parent menu item for this item. Required if is specified as the child of any menu items. -<7> `icon`: (Optional) Enter the menu icon. To use the default icon, set the icon as an (`" "`) empty string. -<8> `title`: (Optional) Enter the menu group title. Only required for adding a new custom main menu item. To hide a default main menu item title from the sidebar, set the title as an (`" "`) empty string. +`default.__`:: (Optional) Enter the menu group parent item name to configure static main menu items. If no `default.__` has a `parent` value set, this field is not needed. +`icon`:: Enter the menu icon. Required for parent menu items. +`title`:: Enter the menu group title. Required for parent menu items. +`priority`:: (Optional) Enter the order of this menu item within its menu level. +`default.__`:: Enter the menu item name for which you want to override the default value. Add the `default.` prefix to identify a main menu item. +`parent`:: (Optional) Enter the parent menu item for this item. Required if is specified as the child of any menu items. +`icon`:: (Optional) Enter the menu icon. To use the default icon, set the icon as an (`" "`) empty string. +`title`:: (Optional) Enter the menu group title. Only required for adding a new custom main menu item. To hide a default main menu item title from the sidebar, set the title as an (`" "`) empty string. // Update <8> for release 1.6 as this option (currently a workaround) would be added as a functionality. RHIDP-6333. -<9> `to`: (Optional) Enter the path that the menu item navigates to. If it is not set, it defaults to the home page. -<10> `priority`: (Optional) Enter the order of this menu item within its menu level. -<11> `enabled`: (Optional) If this field is used to display the menu item in the sidebar, set the value to `true`. To hide the menu item from the sidebar, set the value to `false`. +`to`:: (Optional) Enter the path that the menu item navigates to. If it is not set, it defaults to the home page. +`priority`:: (Optional) Enter the order of this menu item within its menu level. +`enabled`:: (Optional) If this field is used to display the menu item in the sidebar, set the value to `true`. To hide the menu item from the sidebar, set the value to `false`. + -.Example `mainItems` configuration [source,yaml] ---- default.main-menu-items: menuItems: default.catalog: - icon: category # <1> + icon: category title: My Catalog priority: 5 default.learning-path: - title: '' # <2> - default.parentlist: # <3> + title: '' + default.parentlist: title: Overview icon: bookmarks default.home: - parent: default.parentlist # <4> + parent: default.parentlist default.references: - title: References # <5> - icon: school # <6> - to: /references # <7> - enabled: true # <8> + title: References + icon: school + to: /references + enabled: true ---- -<1> `icon`: Specifies if you want to change the icon default menu item for the catalog. -<2> `title`: Specifies an empty string `" "` to hide the learning path from the default sidebar. -<3> `default.parentlist`: Introduces the parent menu item. -<4> `parent`: Nests home menu under the `default.parentlist` parent menu item. -<5> `title`: Specifies a name for `default.references` -<6> `icon`: Displays the `school` icon. -<7> `to`: Redirects `default.references` to the `/references` page. -<8> `enabled`: (Optional) If this field is used to display the menu item in the sidebar, set the value to `true`. To hide the menu item from the sidebar, set the value to `false`. +`icon`:: (Optional) Enter the icon name, such as `category`, bookmarks`, `school`, etc. to change the default icon. +`title`:: Enter an empty string `''` to hide the learning path from the default sidebar. +`default.parentlist`:: Enter the parent menu items. +`parent`:: Enter the parent menu under which to nest the the menu entry, such as `default.parentlist`. +`title`:: Enter the menu entry name, such as `My Catalog`, `Overview` or `References`. +`to`:: Enter the page to redirect to. For example, `default.references` redirects to the `/references` page. +`enabled`:: (Optional) Enter `true` to display the menu item in the sidebar. +Enter `false` to hide the menu item from the sidebar. \ No newline at end of file diff --git a/modules/customizing-the-appearance/proc-overriding-translations.adoc b/modules/customizing-the-appearance/proc-overriding-translations.adoc new file mode 100644 index 0000000000..bda680cf9c --- /dev/null +++ b/modules/customizing-the-appearance/proc-overriding-translations.adoc @@ -0,0 +1,84 @@ +:_mod-docs-content-type: CONCEPT + +[id="prov-overriding-translations_{context}"] += Overriding translations +In {product-very-short} 1.8, English and French are the supported languages. You can implement transalations for other languages by using an `allTranslations.json` file to override existing translation strings and updating the `i18n` section of your `{my-app-config-file}` configuration file. + +.Prerequisitea +* You have enabled localization in your {product-very-short} application. + +.Procedure +. Download the translation strings. +. Create the JSON file containing all your translations, for example: ++ +[id=i18n-enable] +.`allTranslations.json` fragment with translation string overrides +[source,json] +---- +{ + "plugin.npm.translation-ref": { + "en": { + "infoCard.title": "NPM Packet JSON {{packageName}}" + }, + "de": { + "infoCard.title": "NPM Pakettt JSON {{packageName}}" + }, + "zh": { + "infoCard.title": "NPM 包 JSON {{packageName}}" + } + }, + "catalog-import": { + "en": { + "defaultImportPage.headerTitle": "Import an existing Git repository JSON" + }, + "de": { + "defaultImportPage.headerTitle": "Ein vorhandenes Git-Repository importieren JSON" + } + } +} +---- +. Login to your cluster and create a config map for your json translations: ++ +[source,bash] +---- +oc create configmap all-translations --from-file=//allTranslations.json +---- + +. Update your Developer hub helm chart to mount the above config map in the app’s filesystem + +.. In the helm chart -> Root Schema -> Backstage chart schema -> Backstage parameters -> Backstage container additional volume mounts + +.. Select `Add Backstage container additional volume mounts` and add the following ++ +[source,yaml] +---- +MountPath: /opt/app-root/src/translation +Name: all-translations +---- + +.. Add the translations to the `Backstage container additional volumes` in the helm chart ++ +[source,yaml] +---- +name: all-translations +configMap: + defaultMode: 420 + name: all-translations +---- + +. Update the `i18n` section to your custom {product-short} `{my-app-config-file}` configuration file to include the translation override file: ++ +[id=i18n-override] +.`{my-app-config-file}` fragment with localization `i18n` fields +[source,yaml,subs="+quotes"] +---- +i18n: + locales: # List of supported locales. Must include `en`, otherwise the translation framework will fail to load. + - en + - fr + defaultLocale: en # Optional. Defaults to `en` if not specified. + overrides: # List of JSON translation files applied in order (last file wins). Each file may override/add translations for one or more plugins/locales + - /.json + - /.json +---- + diff --git a/modules/customizing-the-appearance/proc-select-rhdh-language.adoc b/modules/customizing-the-appearance/proc-select-rhdh-language.adoc new file mode 100644 index 0000000000..dfa6c335d1 --- /dev/null +++ b/modules/customizing-the-appearance/proc-select-rhdh-language.adoc @@ -0,0 +1,20 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-selecting-rhdh-language_{context}"] += Selecting the language for your {product-short} instance + +You can choose to use one of the following supported languages: + +* English (default) +* French + +.Prerequisites + +* You are logged in to the {product-short} web console. + +.Procedure + +. From the {product-short} web console, click *Settings*. +. From the *Appearance* panel, click the language dropdown to select your language of choice. ++ +image::rhdh/customize-language-dropdown.png[] \ No newline at end of file diff --git a/modules/customizing-the-home-page/proc-customizing-the-home-page-cards.adoc b/modules/customizing-the-home-page/proc-customizing-the-home-page-cards.adoc index 135a660ebc..c3c123a540 100644 --- a/modules/customizing-the-home-page/proc-customizing-the-home-page-cards.adoc +++ b/modules/customizing-the-home-page/proc-customizing-the-home-page-cards.adoc @@ -84,6 +84,9 @@ dynamicPlugins: sm: { w: 10, h: 1, x: 1 } xs: { w: 12, h: 1 } xxs: { w: 12, h: 1 } + props: + path: /search + queryParam: query ---- .Available props @@ -121,6 +124,9 @@ dynamicPlugins: sm: { h: 8 } xs: { h: 8 } xxs: { h: 8 } + props: + title: Quick Access + path: /quickaccess ---- .Available props diff --git a/modules/customizing-the-quick-access-card/proc-using-a-dedicated-service-to-provide-data-to-the-quick-access-card.adoc b/modules/customizing-the-quick-access-card/proc-using-a-dedicated-service-to-provide-data-to-the-quick-access-card.adoc index 94f1ae97b7..7d5603d8a2 100644 --- a/modules/customizing-the-quick-access-card/proc-using-a-dedicated-service-to-provide-data-to-the-quick-access-card.adoc +++ b/modules/customizing-the-quick-access-card/proc-using-a-dedicated-service-to-provide-data-to-the-quick-access-card.adoc @@ -18,7 +18,7 @@ For more information, see {installing-on-ocp-book-link}#assembly-install-rhdh-oc To use a separate service to provide the Home page data, complete the following steps: -. From the *Developer* perspective in the {ocp-brand-name} web console, click *+Add* > *Import from Git*. +. In the {ocp-brand-name} web console, click *+Add* > *Import from Git*. . Enter the URL of your Git repository into the *Git Repo URL* field. + -- @@ -59,7 +59,7 @@ The `red-hat-developer-hub-customization-provider` service contains the 8080 por . Delete the {product-short} pod to ensure that the new configurations are loaded correctly. .Verification -* To view the service, go to the *Administrator* perspective in the {ocp-short} web console and click *Networking* > *Service*. +* To view the service, go to the {ocp-short} web console and click *Networking* > *Service*. + [NOTE] ==== @@ -107,7 +107,7 @@ If the request call fails or is not configured, the {product-short} instance fal ==== * If the images or icons do not load, then allowlist them by adding your image or icon host URLs to the content security policy (csp) `img-src` in your custom ConfigMap as shown in the following example: - ++ [source,yaml,subs="attributes+"] ---- kind: ConfigMap diff --git a/modules/developer-lightspeed/proc-changing-your-llm-provider.adoc b/modules/developer-lightspeed/proc-changing-your-llm-provider.adoc index 87d7676b0f..dee81aabbe 100644 --- a/modules/developer-lightspeed/proc-changing-your-llm-provider.adoc +++ b/modules/developer-lightspeed/proc-changing-your-llm-provider.adoc @@ -28,6 +28,11 @@ lightspeed: url: __ token: __ ---- ++ +[NOTE] +==== +In Developer preview, only one LLM server is supported at a time. +==== ** Optional: You can set the `id`, `url`, and `token` values in a Kubernetes Secret and reference them as environment variables using the `envFrom` section. [source,yaml] ---- diff --git a/modules/developer-lightspeed/proc-installing-and-configuring-lightspeed.adoc b/modules/developer-lightspeed/proc-installing-and-configuring-lightspeed.adoc index b0d92a509d..449e8d9c7c 100644 --- a/modules/developer-lightspeed/proc-installing-and-configuring-lightspeed.adoc +++ b/modules/developer-lightspeed/proc-installing-and-configuring-lightspeed.adoc @@ -71,7 +71,7 @@ data: + [IMPORTANT] ==== -Do not remove the block in the `llm_providers` section. This requirement is crucial when working with {ls-short} because of limitations discovered in Road Core. If you decide to use an alternative LLM provider, you should refer to additional information in the guide. For more information, see link:{developer-lightspeed-link}#proc-changing-your-llm-provider[Changing your LLM provider]. +Do not remove the block in the `llm_providers` section. This requirement is crucial when working with {ls-short} because of limitations discovered in Road Core. If you decide to use an alternative LLM provider, you should refer to additional information in the guide. For more information, see {developer-lightspeed-link}#proc-changing-your-llm-provider_customizing-developer-lightspeed[Changing your LLM provider]. ==== .. Optional: Configure the number of workers that scale the REST API by specifying the following example to the `ols_config.max_workers` parameter in the {rcs-short} ConfigMap. + diff --git a/modules/dynamic-plugins/ref-community-plugins.adoc b/modules/dynamic-plugins/ref-community-plugins.adoc index 81e47f702b..8b13789179 100644 --- a/modules/dynamic-plugins/ref-community-plugins.adoc +++ b/modules/dynamic-plugins/ref-community-plugins.adoc @@ -1,2 +1 @@ -:_mod-docs-content-type: REFERENCE diff --git a/modules/dynamic-plugins/ref-deprecated-plugins.adoc b/modules/dynamic-plugins/ref-deprecated-plugins.adoc new file mode 100644 index 0000000000..81b9d70860 --- /dev/null +++ b/modules/dynamic-plugins/ref-deprecated-plugins.adoc @@ -0,0 +1,34 @@ +:_mod-docs-content-type: REFERENCE + +// This page is generated! Do not edit the .adoc file, but instead run rhdh-supported-plugins.sh to regen this page from the latest plugin metadata. +// cd /path/to/rhdh-documentation; ./modules/dynamic-plugins/rhdh-supported-plugins.sh; ./build/scripts/build.sh; google-chrome titles-generated/main/plugin-rhdh/index.html + +[id="deprecated-plugins"] += Deprecated plugins + +[IMPORTANT] +==== +{product} ({product-very-short}) includes a number of deprecated plugins, which are no longer being actively developed. It is recommended that if you depend on any of these plugins, you migrate to an alternative solution as soon as possible, as these plugins will be removed in a future release. +==== + +{product-very-short} includes the following 2 deprecated plugins: + +[%header,cols=4*] +|=== +|*Name* |*Plugin* |*Version* |*Path and required variables* +|OCM |`https://npmjs.com/package/@backstage-community/plugin-ocm/v/5.6.0[@backstage-community/plugin-ocm]` |5.6.0 +|`./dynamic-plugins/dist/backstage-community-plugin-ocm` + + +|OCM |`https://npmjs.com/package/@backstage-community/plugin-ocm-backend/v/5.7.0[@backstage-community/plugin-ocm-backend]` |5.7.0 +|`./dynamic-plugins/dist/backstage-community-plugin-ocm-backend-dynamic` + +`OCM_HUB_NAME` + +`OCM_HUB_URL` + +`OCM_SA_TOKEN` + + +|=== + diff --git a/modules/dynamic-plugins/ref-deprecated-plugins.template.adoc b/modules/dynamic-plugins/ref-deprecated-plugins.template.adoc new file mode 100644 index 0000000000..8fe3afd38f --- /dev/null +++ b/modules/dynamic-plugins/ref-deprecated-plugins.template.adoc @@ -0,0 +1,21 @@ +:_mod-docs-content-type: REFERENCE + +// This page is generated! Do not edit the .adoc file, but instead run rhdh-supported-plugins.sh to regen this page from the latest plugin metadata. +// cd /path/to/rhdh-documentation; ./modules/dynamic-plugins/rhdh-supported-plugins.sh; ./build/scripts/build.sh; google-chrome titles-generated/main/plugin-rhdh/index.html + +[id="deprecated-plugins"] += Deprecated plugins + +[IMPORTANT] +==== +{product} ({product-very-short}) includes a number of deprecated plugins, which are no longer being actively developed. It is recommended that if you depend on any of these plugins, you migrate to an alternative solution as soon as possible, as these plugins will be removed in a future release. +==== + +{product-very-short} includes the following %%COUNT_4%% deprecated plugins: + +[%header,cols=4*] +|=== +|*Name* |*Plugin* |*Version* |*Path and required variables* +%%TABLE_CONTENT_4%% +|=== + diff --git a/modules/dynamic-plugins/ref-rh-supported-plugins.adoc b/modules/dynamic-plugins/ref-rh-supported-plugins.adoc index 1b40f4e8ea..3cf9f809f1 100644 --- a/modules/dynamic-plugins/ref-rh-supported-plugins.adoc +++ b/modules/dynamic-plugins/ref-rh-supported-plugins.adoc @@ -3,22 +3,27 @@ // This page is generated! Do not edit the .adoc file, but instead run rhdh-supported-plugins.sh to regen this page from the latest plugin metadata. // cd /path/to/rhdh-documentation; ./modules/dynamic-plugins/rhdh-supported-plugins.sh; ./build/scripts/build.sh; google-chrome titles-generated/main/plugin-rhdh/index.html +[id="red-hat-supported-plugins"] = {company-name} supported plugins -{company-name} supports the following 28 plugins: +{company-name} supports the following 26 plugins: [%header,cols=4*] |=== |*Name* |*Plugin* |*Version* |*Path and required variables* -|Analytics Provider Segment |`https://npmjs.com/package/@backstage-community/plugin-analytics-provider-segment/v/1.16.0[@backstage-community/plugin-analytics-provider-segment]` |1.16.0 +|Analytics Provider Segment |`https://npmjs.com/package/@backstage-community/plugin-analytics-provider-segment/v/1.17.0[@backstage-community/plugin-analytics-provider-segment]` |1.17.0 |`./dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment` +`BACKSTAGE_VERSION` + +`RHDH_VERSION` + `SEGMENT_TEST_MODE` `SEGMENT_WRITE_KEY` -|Keycloak |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-keycloak/v/3.12.1[@backstage-community/plugin-catalog-backend-module-keycloak]` |3.12.1 +|Keycloak |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-keycloak/v/3.12.1[@backstage-community/plugin-catalog-backend-module-keycloak]` |3.12.1 |`./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic` `KEYCLOAK_BASE_URL` @@ -32,55 +37,41 @@ `KEYCLOAK_REALM` -|OCM |`https://npmjs.com/package/@backstage-community/plugin-ocm/v/5.6.0[@backstage-community/plugin-ocm]` |5.6.0 -|`./dynamic-plugins/dist/backstage-community-plugin-ocm` - - -|OCM |`https://npmjs.com/package/@backstage-community/plugin-ocm-backend/v/5.7.0[@backstage-community/plugin-ocm-backend]` |5.7.0 -|`./dynamic-plugins/dist/backstage-community-plugin-ocm-backend-dynamic` - -`OCM_HUB_NAME` - -`OCM_HUB_URL` - -`OCM_SA_TOKEN` - - -|Quay |`https://npmjs.com/package/@backstage-community/plugin-quay/v/1.21.1[@backstage-community/plugin-quay]` |1.21.1 +|Quay |`https://npmjs.com/package/@backstage-community/plugin-quay/v/1.21.1[@backstage-community/plugin-quay]` |1.21.1 |`./dynamic-plugins/dist/backstage-community-plugin-quay` -|RBAC |`https://npmjs.com/package/@backstage-community/plugin-rbac/v/1.42.0[@backstage-community/plugin-rbac]` |1.42.0 +|RBAC |`https://npmjs.com/package/@backstage-community/plugin-rbac/v/1.42.0[@backstage-community/plugin-rbac]` |1.42.0 |`./dynamic-plugins/dist/backstage-community-plugin-rbac` -|Kubernetes |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-kubernetes/v/2.8.1[@backstage-community/plugin-scaffolder-backend-module-kubernetes]` |2.8.1 +|Kubernetes |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-kubernetes/v/2.8.1[@backstage-community/plugin-scaffolder-backend-module-kubernetes]` |2.8.1 |`./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-kubernetes-dynamic` -|Quay |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-quay/v/2.9.1[@backstage-community/plugin-scaffolder-backend-module-quay]` |2.9.1 +|Quay |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-quay/v/2.9.1[@backstage-community/plugin-scaffolder-backend-module-quay]` |2.9.1 |`./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-quay-dynamic` -|Regex |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-regex/v/2.7.0[@backstage-community/plugin-scaffolder-backend-module-regex]` |2.7.0 +|Regex |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-regex/v/2.7.0[@backstage-community/plugin-scaffolder-backend-module-regex]` |2.7.0 |`./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-regex-dynamic` -|Tekton |`https://npmjs.com/package/@backstage-community/plugin-tekton/v/3.26.2[@backstage-community/plugin-tekton]` |3.26.2 +|Tekton |`https://npmjs.com/package/@backstage-community/plugin-tekton/v/3.26.2[@backstage-community/plugin-tekton]` |3.26.2 |`./dynamic-plugins/dist/backstage-community-plugin-tekton` -|Topology |`https://npmjs.com/package/@backstage-community/plugin-topology/v/2.2.2[@backstage-community/plugin-topology]` |2.2.2 +|Topology |`https://npmjs.com/package/@backstage-community/plugin-topology/v/2.2.2[@backstage-community/plugin-topology]` |2.2.2 |`./dynamic-plugins/dist/backstage-community-plugin-topology` -|GitHub |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-github/v/0.9.0[@backstage/plugin-catalog-backend-module-github]` |0.9.0 +|GitHub |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-github/v/0.9.0[@backstage/plugin-catalog-backend-module-github]` |0.9.0 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic` `GITHUB_ORG` -|GitHub Org |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-github-org/v/0.3.10[@backstage/plugin-catalog-backend-module-github-org]` |0.3.10 +|GitHub Org |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-github-org/v/0.3.10[@backstage/plugin-catalog-backend-module-github-org]` |0.3.10 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic` `GITHUB_ORG` @@ -88,11 +79,11 @@ `GITHUB_URL` -|Ldap |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-ldap/v/0.11.5[@backstage/plugin-catalog-backend-module-ldap]` |0.11.5 +|Ldap |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-ldap/v/0.11.5[@backstage/plugin-catalog-backend-module-ldap]` |0.11.5 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-ldap-dynamic` -|Kubernetes |`https://npmjs.com/package/@backstage/plugin-kubernetes-backend/v/0.19.6[@backstage/plugin-kubernetes-backend]` |0.19.6 +|Kubernetes |`https://npmjs.com/package/@backstage/plugin-kubernetes-backend/v/0.19.6[@backstage/plugin-kubernetes-backend]` |0.19.6 |`./dynamic-plugins/dist/backstage-plugin-kubernetes-backend-dynamic` `K8S_CLUSTER_NAME` @@ -102,55 +93,55 @@ `K8S_CLUSTER_URL` -|GitHub |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-github/v/0.7.1[@backstage/plugin-scaffolder-backend-module-github]` |0.7.1 +|GitHub |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-github/v/0.7.1[@backstage/plugin-scaffolder-backend-module-github]` |0.7.1 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-github-dynamic` -|Signals |`https://npmjs.com/package/@backstage/plugin-signals-backend/v/0.3.4[@backstage/plugin-signals-backend]` |0.3.4 +|Signals |`https://npmjs.com/package/@backstage/plugin-signals-backend/v/0.3.4[@backstage/plugin-signals-backend]` |0.3.4 |`./dynamic-plugins/dist/backstage-plugin-signals-backend-dynamic` -|TechDocs |`https://npmjs.com/package/@backstage/plugin-techdocs/v/1.12.6[@backstage/plugin-techdocs]` |1.12.6 +|TechDocs |`https://npmjs.com/package/@backstage/plugin-techdocs/v/1.12.6[@backstage/plugin-techdocs]` |1.12.6 |`./dynamic-plugins/dist/backstage-plugin-techdocs` -|TechDocs |`https://npmjs.com/package/@backstage/plugin-techdocs-backend/v/2.0.2[@backstage/plugin-techdocs-backend]` |2.0.2 +|TechDocs |`https://npmjs.com/package/@backstage/plugin-techdocs-backend/v/2.0.2[@backstage/plugin-techdocs-backend]` |2.0.2 |`./dynamic-plugins/dist/backstage-plugin-techdocs-backend-dynamic` -|TechDocs Module Addons Contrib |`https://npmjs.com/package/@backstage/plugin-techdocs-module-addons-contrib/v/1.1.24[@backstage/plugin-techdocs-module-addons-contrib]` |1.1.24 +|TechDocs Module Addons Contrib |`https://npmjs.com/package/@backstage/plugin-techdocs-module-addons-contrib/v/1.1.24[@backstage/plugin-techdocs-module-addons-contrib]` |1.1.24 |`./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib` -|Dynamic Home Page |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-dynamic-home-page/v/1.5.0[@red-hat-developer-hub/backstage-plugin-dynamic-home-page]` |1.5.0 +|Dynamic Home Page |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-dynamic-home-page/v/1.5.0[@red-hat-developer-hub/backstage-plugin-dynamic-home-page]` |1.5.0 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-dynamic-home-page` -|Global Floating Action Button |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-global-floating-action-button/v/1.2.0[@red-hat-developer-hub/backstage-plugin-global-floating-action-button]` |1.2.0 +|Global Floating Action Button |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-global-floating-action-button/v/1.2.0[@red-hat-developer-hub/backstage-plugin-global-floating-action-button]` |1.2.0 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button` -|Global Header |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-global-header/v/1.13.0[@red-hat-developer-hub/backstage-plugin-global-header]` |1.13.0 +|Global Header |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-global-header/v/1.13.0[@red-hat-developer-hub/backstage-plugin-global-header]` |1.13.0 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header` -|Adoption Insights |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-adoption-insights/v/0.2.1[@red-hat-developer-hub/backstage-plugin-adoption-insights]` |0.2.1 +|Adoption Insights |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-adoption-insights/v/0.2.1[@red-hat-developer-hub/backstage-plugin-adoption-insights]` |0.2.1 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-adoption-insights` -|Adoption Insights |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-adoption-insights-backend/v/0.2.1[@red-hat-developer-hub/backstage-plugin-adoption-insights-backend]` |0.2.1 +|Adoption Insights |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-adoption-insights-backend/v/0.2.1[@red-hat-developer-hub/backstage-plugin-adoption-insights-backend]` |0.2.1 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-adoption-insights-backend-dynamic` -|Analytics Module Adoption Insights |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-analytics-module-adoption-insights/v/0.2.0[@red-hat-developer-hub/backstage-plugin-analytics-module-adoption-insights]` |0.2.0 +|Analytics Module Adoption Insights |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-analytics-module-adoption-insights/v/0.2.0[@red-hat-developer-hub/backstage-plugin-analytics-module-adoption-insights]` |0.2.0 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-analytics-module-adoption-insights-dynamic` -|Quickstart |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-quickstart/v/1.1.1[@red-hat-developer-hub/backstage-plugin-quickstart]` |1.1.1 +|Quickstart |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-quickstart/v/1.6.2[@red-hat-developer-hub/backstage-plugin-quickstart]` |1.6.2 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-quickstart` -|Argo CD |`https://npmjs.com/package/@roadiehq/backstage-plugin-argo-cd-backend/v/4.3.1[@roadiehq/backstage-plugin-argo-cd-backend]` |4.3.1 +|Argo CD |`https://npmjs.com/package/@roadiehq/backstage-plugin-argo-cd-backend/v/4.3.1[@roadiehq/backstage-plugin-argo-cd-backend]` |4.3.1 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-argo-cd-backend-dynamic` `ARGOCD_AUTH_TOKEN` diff --git a/modules/dynamic-plugins/ref-rh-tech-preview-plugins.adoc b/modules/dynamic-plugins/ref-rh-tech-preview-plugins.adoc index 0c07651cbe..aaa2bc44d2 100644 --- a/modules/dynamic-plugins/ref-rh-tech-preview-plugins.adoc +++ b/modules/dynamic-plugins/ref-rh-tech-preview-plugins.adoc @@ -2,7 +2,7 @@ // This page is generated! Do not edit the .adoc file, but instead run rhdh-supported-plugins.sh to regen this page from the latest plugin metadata. // cd /path/to/rhdh-documentation; ./modules/dynamic-plugins/rhdh-supported-plugins.sh; ./build/scripts/build.sh; google-chrome titles-generated/main/plugin-rhdh/index.html - +[id="red-hat-technology-preview-plugins"] = {company-name} Technology Preview plugins {company-name} provides Technology Preview support for the following 54 plugins: @@ -10,7 +10,7 @@ [%header,cols=4*] |=== |*Name* |*Plugin* |*Version* |*Path and required variables* -|3scale |`https://npmjs.com/package/@backstage-community/plugin-3scale-backend/v/3.6.1[@backstage-community/plugin-3scale-backend]` |3.6.1 +|3scale |`https://npmjs.com/package/@backstage-community/plugin-3scale-backend/v/3.6.1[@backstage-community/plugin-3scale-backend]` |3.6.1 |`./dynamic-plugins/dist/backstage-community-plugin-3scale-backend-dynamic` `THREESCALE_ACCESS_TOKEN` @@ -18,15 +18,15 @@ `THREESCALE_BASE_URL` -|ACR |`https://npmjs.com/package/@backstage-community/plugin-acr/v/1.15.1[@backstage-community/plugin-acr]` |1.15.1 +|ACR |`https://npmjs.com/package/@backstage-community/plugin-acr/v/1.15.1[@backstage-community/plugin-acr]` |1.15.1 |`./dynamic-plugins/dist/backstage-community-plugin-acr` -|Azure Devops |`https://npmjs.com/package/@backstage-community/plugin-azure-devops/v/0.16.1[@backstage-community/plugin-azure-devops]` |0.16.1 +|Azure Devops |`https://npmjs.com/package/@backstage-community/plugin-azure-devops/v/0.16.1[@backstage-community/plugin-azure-devops]` |0.16.1 |`./dynamic-plugins/dist/backstage-community-plugin-azure-devops` -|Azure Devops |`https://npmjs.com/package/@backstage-community/plugin-azure-devops-backend/v/0.17.1[@backstage-community/plugin-azure-devops-backend]` |0.17.1 +|Azure Devops |`https://npmjs.com/package/@backstage-community/plugin-azure-devops-backend/v/0.17.1[@backstage-community/plugin-azure-devops-backend]` |0.17.1 |`./dynamic-plugins/dist/backstage-community-plugin-azure-devops-backend-dynamic` `AZURE_ORG` @@ -34,31 +34,31 @@ `AZURE_TOKEN` -|Pingidentity |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-pingidentity/v/0.5.0[@backstage-community/plugin-catalog-backend-module-pingidentity]` |0.5.0 +|Pingidentity |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-pingidentity/v/0.5.0[@backstage-community/plugin-catalog-backend-module-pingidentity]` |0.5.0 |`./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-pingidentity-dynamic` -|Scaffolder Relation Processor |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor/v/2.5.0[@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor]` |2.5.0 +|Scaffolder Relation Processor |`https://npmjs.com/package/@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor/v/2.5.0[@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor]` |2.5.0 |`./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-scaffolder-relation-processor-dynamic` -|Dynatrace |`https://npmjs.com/package/@backstage-community/plugin-dynatrace/v/10.6.0[@backstage-community/plugin-dynatrace]` |10.6.0 +|Dynatrace |`https://npmjs.com/package/@backstage-community/plugin-dynatrace/v/10.6.0[@backstage-community/plugin-dynatrace]` |10.6.0 |`./dynamic-plugins/dist/backstage-community-plugin-dynatrace` -|GitHub Actions |`https://npmjs.com/package/@backstage-community/plugin-github-actions/v/0.11.1[@backstage-community/plugin-github-actions]` |0.11.1 +|GitHub Actions |`https://npmjs.com/package/@backstage-community/plugin-github-actions/v/0.11.1[@backstage-community/plugin-github-actions]` |0.11.1 |`./dynamic-plugins/dist/backstage-community-plugin-github-actions` -|GitHub Issues |`https://npmjs.com/package/@backstage-community/plugin-github-issues/v/0.10.0[@backstage-community/plugin-github-issues]` |0.10.0 +|GitHub Issues |`https://npmjs.com/package/@backstage-community/plugin-github-issues/v/0.10.0[@backstage-community/plugin-github-issues]` |0.10.0 |`./dynamic-plugins/dist/backstage-community-plugin-github-issues` -|Jenkins |`https://npmjs.com/package/@backstage-community/plugin-jenkins/v/0.20.0[@backstage-community/plugin-jenkins]` |0.20.0 +|Jenkins |`https://npmjs.com/package/@backstage-community/plugin-jenkins/v/0.20.0[@backstage-community/plugin-jenkins]` |0.20.0 |`./dynamic-plugins/dist/backstage-community-plugin-jenkins` -|Jenkins |`https://npmjs.com/package/@backstage-community/plugin-jenkins-backend/v/0.15.0[@backstage-community/plugin-jenkins-backend]` |0.15.0 +|Jenkins |`https://npmjs.com/package/@backstage-community/plugin-jenkins-backend/v/0.15.0[@backstage-community/plugin-jenkins-backend]` |0.15.0 |`./dynamic-plugins/dist/backstage-community-plugin-jenkins-backend-dynamic` `JENKINS_TOKEN` @@ -68,23 +68,23 @@ `JENKINS_USERNAME` -|JFrog Artifactory |`https://npmjs.com/package/@backstage-community/plugin-jfrog-artifactory/v/1.15.3[@backstage-community/plugin-jfrog-artifactory]` |1.15.3 +|JFrog Artifactory |`https://npmjs.com/package/@backstage-community/plugin-jfrog-artifactory/v/1.15.3[@backstage-community/plugin-jfrog-artifactory]` |1.15.3 |`./dynamic-plugins/dist/backstage-community-plugin-jfrog-artifactory` -|Lighthouse |`https://npmjs.com/package/@backstage-community/plugin-lighthouse/v/0.10.0[@backstage-community/plugin-lighthouse]` |0.10.0 +|Lighthouse |`https://npmjs.com/package/@backstage-community/plugin-lighthouse/v/0.10.0[@backstage-community/plugin-lighthouse]` |0.10.0 |`./dynamic-plugins/dist/backstage-community-plugin-lighthouse` -|Nexus Repository Manager |`https://npmjs.com/package/@backstage-community/plugin-nexus-repository-manager/v/1.14.1[@backstage-community/plugin-nexus-repository-manager]` |1.14.1 +|Nexus Repository Manager |`https://npmjs.com/package/@backstage-community/plugin-nexus-repository-manager/v/1.14.1[@backstage-community/plugin-nexus-repository-manager]` |1.14.1 |`./dynamic-plugins/dist/backstage-community-plugin-nexus-repository-manager` -|Argo CD (Red Hat) |`https://npmjs.com/package/@backstage-community/plugin-redhat-argocd/v/1.21.2[@backstage-community/plugin-redhat-argocd]` |1.21.2 +|Argo CD (Red Hat) |`https://npmjs.com/package/@backstage-community/plugin-redhat-argocd/v/1.25.1[@backstage-community/plugin-redhat-argocd]` |1.25.1 |`./dynamic-plugins/dist/backstage-community-plugin-redhat-argocd` -|ServiceNow |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-servicenow/v/2.7.0[@backstage-community/plugin-scaffolder-backend-module-servicenow]` |2.7.0 +|ServiceNow |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-servicenow/v/2.7.0[@backstage-community/plugin-scaffolder-backend-module-servicenow]` |2.7.0 |`./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-servicenow-dynamic` `SERVICENOW_BASE_URL` @@ -94,15 +94,15 @@ `SERVICENOW_USERNAME` -|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-sonarqube/v/2.7.1[@backstage-community/plugin-scaffolder-backend-module-sonarqube]` |2.7.1 +|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-scaffolder-backend-module-sonarqube/v/2.7.1[@backstage-community/plugin-scaffolder-backend-module-sonarqube]` |2.7.1 |`./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-sonarqube-dynamic` -|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-sonarqube/v/0.13.0[@backstage-community/plugin-sonarqube]` |0.13.0 +|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-sonarqube/v/0.13.0[@backstage-community/plugin-sonarqube]` |0.13.0 |`./dynamic-plugins/dist/backstage-community-plugin-sonarqube` -|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-sonarqube-backend/v/0.9.2[@backstage-community/plugin-sonarqube-backend]` |0.9.2 +|SonarQube |`https://npmjs.com/package/@backstage-community/plugin-sonarqube-backend/v/0.9.2[@backstage-community/plugin-sonarqube-backend]` |0.9.2 |`./dynamic-plugins/dist/backstage-community-plugin-sonarqube-backend-dynamic` `SONARQUBE_TOKEN` @@ -110,37 +110,37 @@ `SONARQUBE_URL` -|Tech Radar |`https://npmjs.com/package/@backstage-community/plugin-tech-radar/v/1.7.1[@backstage-community/plugin-tech-radar]` |1.7.1 +|Tech Radar |`https://npmjs.com/package/@backstage-community/plugin-tech-radar/v/1.7.1[@backstage-community/plugin-tech-radar]` |1.7.1 |`./dynamic-plugins/dist/backstage-community-plugin-tech-radar` -|Tech Radar |`https://npmjs.com/package/@backstage-community/plugin-tech-radar-backend/v/1.6.0[@backstage-community/plugin-tech-radar-backend]` |1.6.0 +|Tech Radar |`https://npmjs.com/package/@backstage-community/plugin-tech-radar-backend/v/1.6.0[@backstage-community/plugin-tech-radar-backend]` |1.6.0 |`./dynamic-plugins/dist/backstage-community-plugin-tech-radar-backend-dynamic` `TECH_RADAR_DATA_URL` -|Bitbucket Cloud |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-bitbucket-cloud/v/0.4.8[@backstage/plugin-catalog-backend-module-bitbucket-cloud]` |0.4.8 +|Bitbucket Cloud |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-bitbucket-cloud/v/0.4.8[@backstage/plugin-catalog-backend-module-bitbucket-cloud]` |0.4.8 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-bitbucket-cloud-dynamic` `BITBUCKET_WORKSPACE` -|Bitbucket Server |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-bitbucket-server/v/0.4.1[@backstage/plugin-catalog-backend-module-bitbucket-server]` |0.4.1 +|Bitbucket Server |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-bitbucket-server/v/0.4.1[@backstage/plugin-catalog-backend-module-bitbucket-server]` |0.4.1 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-bitbucket-server-dynamic` `BITBUCKET_HOST` -|GitLab |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-gitlab/v/0.6.6[@backstage/plugin-catalog-backend-module-gitlab]` |0.6.6 +|GitLab |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-gitlab/v/0.6.6[@backstage/plugin-catalog-backend-module-gitlab]` |0.6.6 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-dynamic` -|GitLab Org |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-gitlab-org/v/0.2.9[@backstage/plugin-catalog-backend-module-gitlab-org]` |0.2.9 +|GitLab Org |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-gitlab-org/v/0.2.9[@backstage/plugin-catalog-backend-module-gitlab-org]` |0.2.9 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-org-dynamic` -|MS Graph |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-msgraph/v/0.7.0[@backstage/plugin-catalog-backend-module-msgraph]` |0.7.0 +|MS Graph |`https://npmjs.com/package/@backstage/plugin-catalog-backend-module-msgraph/v/0.7.0[@backstage/plugin-catalog-backend-module-msgraph]` |0.7.0 |`./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic` `MICROSOFT_CLIENT_ID` @@ -150,19 +150,19 @@ `MICROSOFT_TENANT_ID` -|Kubernetes |`https://npmjs.com/package/@backstage/plugin-kubernetes/v/0.12.7[@backstage/plugin-kubernetes]` |0.12.7 +|Kubernetes |`https://npmjs.com/package/@backstage/plugin-kubernetes/v/0.12.7[@backstage/plugin-kubernetes]` |0.12.7 |`./dynamic-plugins/dist/backstage-plugin-kubernetes` -|Notifications |`https://npmjs.com/package/@backstage/plugin-notifications/v/0.5.5[@backstage/plugin-notifications]` |0.5.5 +|Notifications |`https://npmjs.com/package/@backstage/plugin-notifications/v/0.5.5[@backstage/plugin-notifications]` |0.5.5 |`./dynamic-plugins/dist/backstage-plugin-notifications` -|Notifications |`https://npmjs.com/package/@backstage/plugin-notifications-backend/v/0.5.6[@backstage/plugin-notifications-backend]` |0.5.6 +|Notifications |`https://npmjs.com/package/@backstage/plugin-notifications-backend/v/0.5.6[@backstage/plugin-notifications-backend]` |0.5.6 |`./dynamic-plugins/dist/backstage-plugin-notifications-backend-dynamic` -|Notifications |`https://npmjs.com/package/@backstage/plugin-notifications-backend-module-email/v/0.3.9[@backstage/plugin-notifications-backend-module-email]` |0.3.9 +|Notifications |`https://npmjs.com/package/@backstage/plugin-notifications-backend-module-email/v/0.3.9[@backstage/plugin-notifications-backend-module-email]` |0.3.9 |`./dynamic-plugins/dist/backstage-plugin-notifications-backend-module-email-dynamic` `EMAIL_HOSTNAME` @@ -174,35 +174,35 @@ `EMAIL_USERNAME` -|Azure |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-azure/v/0.2.9[@backstage/plugin-scaffolder-backend-module-azure]` |0.2.9 +|Azure |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-azure/v/0.2.9[@backstage/plugin-scaffolder-backend-module-azure]` |0.2.9 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-azure-dynamic` -|Bitbucket Cloud |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-bitbucket-cloud/v/0.2.9[@backstage/plugin-scaffolder-backend-module-bitbucket-cloud]` |0.2.9 +|Bitbucket Cloud |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-bitbucket-cloud/v/0.2.9[@backstage/plugin-scaffolder-backend-module-bitbucket-cloud]` |0.2.9 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-bitbucket-cloud-dynamic` -|Bitbucket Server |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-bitbucket-server/v/0.2.9[@backstage/plugin-scaffolder-backend-module-bitbucket-server]` |0.2.9 +|Bitbucket Server |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-bitbucket-server/v/0.2.9[@backstage/plugin-scaffolder-backend-module-bitbucket-server]` |0.2.9 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-bitbucket-server-dynamic` -|Gerrit |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-gerrit/v/0.2.9[@backstage/plugin-scaffolder-backend-module-gerrit]` |0.2.9 +|Gerrit |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-gerrit/v/0.2.9[@backstage/plugin-scaffolder-backend-module-gerrit]` |0.2.9 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-gerrit-dynamic` -|GitLab |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-gitlab/v/0.9.1[@backstage/plugin-scaffolder-backend-module-gitlab]` |0.9.1 +|GitLab |`https://npmjs.com/package/@backstage/plugin-scaffolder-backend-module-gitlab/v/0.9.1[@backstage/plugin-scaffolder-backend-module-gitlab]` |0.9.1 |`./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-gitlab-dynamic` -|Signals |`https://npmjs.com/package/@backstage/plugin-signals/v/0.0.19[@backstage/plugin-signals]` |0.0.19 +|Signals |`https://npmjs.com/package/@backstage/plugin-signals/v/0.0.19[@backstage/plugin-signals]` |0.0.19 |`./dynamic-plugins/dist/backstage-plugin-signals` -|GitLab |`https://npmjs.com/package/@immobiliarelabs/backstage-plugin-gitlab/v/6.12.1[@immobiliarelabs/backstage-plugin-gitlab]` |6.12.1 +|GitLab |`https://npmjs.com/package/@immobiliarelabs/backstage-plugin-gitlab/v/6.12.1[@immobiliarelabs/backstage-plugin-gitlab]` |6.12.1 |`./dynamic-plugins/dist/immobiliarelabs-backstage-plugin-gitlab` -|GitLab |`https://npmjs.com/package/@immobiliarelabs/backstage-plugin-gitlab-backend/v/6.12.0[@immobiliarelabs/backstage-plugin-gitlab-backend]` |6.12.0 +|GitLab |`https://npmjs.com/package/@immobiliarelabs/backstage-plugin-gitlab-backend/v/6.12.0[@immobiliarelabs/backstage-plugin-gitlab-backend]` |6.12.0 |`./dynamic-plugins/dist/immobiliarelabs-backstage-plugin-gitlab-backend-dynamic` `GITLAB_HOST` @@ -210,11 +210,11 @@ `GITLAB_TOKEN` -|PagerDuty |`https://npmjs.com/package/@pagerduty/backstage-plugin/v/0.15.5[@pagerduty/backstage-plugin]` |0.15.5 +|PagerDuty |`https://npmjs.com/package/@pagerduty/backstage-plugin/v/0.15.5[@pagerduty/backstage-plugin]` |0.15.5 |`./dynamic-plugins/dist/pagerduty-backstage-plugin` -|PagerDuty |`https://npmjs.com/package/@pagerduty/backstage-plugin-backend/v/0.9.6[@pagerduty/backstage-plugin-backend]` |0.9.6 +|PagerDuty |`https://npmjs.com/package/@pagerduty/backstage-plugin-backend/v/0.9.6[@pagerduty/backstage-plugin-backend]` |0.9.6 |`./dynamic-plugins/dist/pagerduty-backstage-plugin-backend-dynamic` `PAGERDUTY_API_BASE` @@ -226,51 +226,51 @@ `PAGERDUTY_SUBDOMAIN` -|Azure Repositories |`https://npmjs.com/package/@parfuemerie-douglas/scaffolder-backend-module-azure-repositories/v/0.3.0[@parfuemerie-douglas/scaffolder-backend-module-azure-repositories]` |0.3.0 +|Azure Repositories |`https://npmjs.com/package/@parfuemerie-douglas/scaffolder-backend-module-azure-repositories/v/0.3.0[@parfuemerie-douglas/scaffolder-backend-module-azure-repositories]` |0.3.0 |`./dynamic-plugins/dist/parfuemerie-douglas-scaffolder-backend-module-azure-repositories-dynamic` -|Bulk Import |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-bulk-import/v/1.13.4[@red-hat-developer-hub/backstage-plugin-bulk-import]` |1.13.4 +|Bulk Import |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-bulk-import/v/1.13.4[@red-hat-developer-hub/backstage-plugin-bulk-import]` |1.13.4 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import` -|Bulk Import |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-bulk-import-backend/v/6.1.7[@red-hat-developer-hub/backstage-plugin-bulk-import-backend]` |6.1.7 +|Bulk Import |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-bulk-import-backend/v/6.1.7[@red-hat-developer-hub/backstage-plugin-bulk-import-backend]` |6.1.7 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import-backend-dynamic` -|Marketplace |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-catalog-backend-module-marketplace/v/0.4.4[@red-hat-developer-hub/backstage-plugin-catalog-backend-module-marketplace]` |0.4.4 +|Marketplace |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-catalog-backend-module-marketplace/v/0.4.4[@red-hat-developer-hub/backstage-plugin-catalog-backend-module-marketplace]` |0.4.4 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-catalog-backend-module-marketplace-dynamic` -|Marketplace |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-marketplace/v/0.8.5[@red-hat-developer-hub/backstage-plugin-marketplace]` |0.8.5 +|Marketplace |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-marketplace/v/0.8.5[@red-hat-developer-hub/backstage-plugin-marketplace]` |0.8.5 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace` -|Marketplace |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-marketplace-backend/v/0.7.3[@red-hat-developer-hub/backstage-plugin-marketplace-backend]` |0.7.3 +|Marketplace |`https://npmjs.com/package/@red-hat-developer-hub/backstage-plugin-marketplace-backend/v/0.7.3[@red-hat-developer-hub/backstage-plugin-marketplace-backend]` |0.7.3 |`./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-marketplace-backend-dynamic` -|Datadog |`https://npmjs.com/package/@roadiehq/backstage-plugin-datadog/v/2.4.3[@roadiehq/backstage-plugin-datadog]` |2.4.3 +|Datadog |`https://npmjs.com/package/@roadiehq/backstage-plugin-datadog/v/2.4.3[@roadiehq/backstage-plugin-datadog]` |2.4.3 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-datadog` -|GitHub Insights |`https://npmjs.com/package/@roadiehq/backstage-plugin-github-insights/v/3.1.4[@roadiehq/backstage-plugin-github-insights]` |3.1.4 +|GitHub Insights |`https://npmjs.com/package/@roadiehq/backstage-plugin-github-insights/v/3.1.4[@roadiehq/backstage-plugin-github-insights]` |3.1.4 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-github-insights` -|GitHub Pull Requests |`https://npmjs.com/package/@roadiehq/backstage-plugin-github-pull-requests/v/3.4.2[@roadiehq/backstage-plugin-github-pull-requests]` |3.4.2 +|GitHub Pull Requests |`https://npmjs.com/package/@roadiehq/backstage-plugin-github-pull-requests/v/3.4.2[@roadiehq/backstage-plugin-github-pull-requests]` |3.4.2 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-github-pull-requests` -|Jira |`https://npmjs.com/package/@roadiehq/backstage-plugin-jira/v/2.9.0[@roadiehq/backstage-plugin-jira]` |2.9.0 +|Jira |`https://npmjs.com/package/@roadiehq/backstage-plugin-jira/v/2.9.0[@roadiehq/backstage-plugin-jira]` |2.9.0 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-jira` -|Security Insights |`https://npmjs.com/package/@roadiehq/backstage-plugin-security-insights/v/3.1.3[@roadiehq/backstage-plugin-security-insights]` |3.1.3 +|Security Insights |`https://npmjs.com/package/@roadiehq/backstage-plugin-security-insights/v/3.1.3[@roadiehq/backstage-plugin-security-insights]` |3.1.3 |`./dynamic-plugins/dist/roadiehq-backstage-plugin-security-insights` -|Argo CD |`https://npmjs.com/package/@roadiehq/scaffolder-backend-argocd/v/1.6.0[@roadiehq/scaffolder-backend-argocd]` |1.6.0 +|Argo CD |`https://npmjs.com/package/@roadiehq/scaffolder-backend-argocd/v/1.6.0[@roadiehq/scaffolder-backend-argocd]` |1.6.0 |`./dynamic-plugins/dist/roadiehq-scaffolder-backend-argocd-dynamic` `ARGOCD_AUTH_TOKEN` @@ -286,11 +286,11 @@ `ARGOCD_USERNAME` -|Http Request |`https://npmjs.com/package/@roadiehq/scaffolder-backend-module-http-request/v/5.3.4[@roadiehq/scaffolder-backend-module-http-request]` |5.3.4 +|Http Request |`https://npmjs.com/package/@roadiehq/scaffolder-backend-module-http-request/v/5.3.4[@roadiehq/scaffolder-backend-module-http-request]` |5.3.4 |`./dynamic-plugins/dist/roadiehq-scaffolder-backend-module-http-request-dynamic` -|Utils |`https://npmjs.com/package/@roadiehq/scaffolder-backend-module-utils/v/3.5.0[@roadiehq/scaffolder-backend-module-utils]` |3.5.0 +|Utils |`https://npmjs.com/package/@roadiehq/scaffolder-backend-module-utils/v/3.5.0[@roadiehq/scaffolder-backend-module-utils]` |3.5.0 |`./dynamic-plugins/dist/roadiehq-scaffolder-backend-module-utils-dynamic` diff --git a/modules/dynamic-plugins/rhdh-supported-plugins.csv b/modules/dynamic-plugins/rhdh-supported-plugins.csv index 07fe7ab778..6c3356f5ff 100644 --- a/modules/dynamic-plugins/rhdh-supported-plugins.csv +++ b/modules/dynamic-plugins/rhdh-supported-plugins.csv @@ -2,23 +2,21 @@ "Adoption Insights","@red-hat-developer-hub/backstage-plugin-adoption-insights","Frontend","0.2.1","Production","active","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-adoption-insights",";","Enabled" "Adoption Insights","@red-hat-developer-hub/backstage-plugin-adoption-insights-backend","Backend","0.2.1","Production","active","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-adoption-insights-backend-dynamic",";","Enabled" "Analytics Module Adoption Insights","@red-hat-developer-hub/backstage-plugin-analytics-module-adoption-insights","Frontend","0.2.0","Production","active","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-analytics-module-adoption-insights-dynamic",";","Enabled" -"Analytics Provider Segment","@backstage-community/plugin-analytics-provider-segment","Frontend","1.16.0","Production","active","./dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment","`SEGMENT_TEST_MODE`;`SEGMENT_WRITE_KEY`;","Enabled" +"Analytics Provider Segment","@backstage-community/plugin-analytics-provider-segment","Frontend","1.17.0","Production","active","./dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment","`BACKSTAGE_VERSION`;`RHDH_VERSION`;`SEGMENT_TEST_MODE`;`SEGMENT_WRITE_KEY`;","Enabled" "Argo CD","@roadiehq/backstage-plugin-argo-cd-backend","Backend","4.3.1","Production","active","./dynamic-plugins/dist/roadiehq-backstage-plugin-argo-cd-backend-dynamic","`ARGOCD_AUTH_TOKEN`;`ARGOCD_AUTH_TOKEN2`;`ARGOCD_INSTANCE1_URL`;`ARGOCD_INSTANCE2_URL`;`ARGOCD_PASSWORD`;`ARGOCD_USERNAME`;","Disabled" "Dynamic Home Page","@red-hat-developer-hub/backstage-plugin-dynamic-home-page","Frontend","1.5.0","Production","active","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-dynamic-home-page",";","Enabled" -"GitHub Org","@backstage/plugin-catalog-backend-module-github-org","Backend","0.3.10","Production","active","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic","`GITHUB_ORG`;`GITHUB_URL`;","Disabled" "GitHub","@backstage/plugin-catalog-backend-module-github","Backend","0.9.0","Production","active","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic","`GITHUB_ORG`;","Disabled" "GitHub","@backstage/plugin-scaffolder-backend-module-github","Backend","0.7.1","Production","active","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-github-dynamic",";","Disabled" +"GitHub Org","@backstage/plugin-catalog-backend-module-github-org","Backend","0.3.10","Production","active","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic","`GITHUB_ORG`;`GITHUB_URL`;","Disabled" "Global Floating Action Button","@red-hat-developer-hub/backstage-plugin-global-floating-action-button","Frontend","1.2.0","Production","active","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button",";","Enabled" "Global Header","@red-hat-developer-hub/backstage-plugin-global-header","Frontend","1.13.0","Production","active","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header",";","Enabled" "Keycloak","@backstage-community/plugin-catalog-backend-module-keycloak","Backend","3.12.1","Production","active","./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-keycloak-dynamic","`KEYCLOAK_BASE_URL`;`KEYCLOAK_CLIENT_ID`;`KEYCLOAK_CLIENT_SECRET`;`KEYCLOAK_LOGIN_REALM`;`KEYCLOAK_REALM`;","Disabled" "Kubernetes","@backstage/plugin-kubernetes-backend","Backend","0.19.6","Production","active","./dynamic-plugins/dist/backstage-plugin-kubernetes-backend-dynamic","`K8S_CLUSTER_NAME`;`K8S_CLUSTER_TOKEN`;`K8S_CLUSTER_URL`;","Disabled" "Kubernetes","@backstage-community/plugin-scaffolder-backend-module-kubernetes","Backend","2.8.1","Production","active","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-kubernetes-dynamic",";","Disabled" "Ldap","@backstage/plugin-catalog-backend-module-ldap","Backend","0.11.5","Production","active","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-ldap-dynamic",";","Disabled" -"OCM","@backstage-community/plugin-ocm","Frontend","5.6.0","Production","active","./dynamic-plugins/dist/backstage-community-plugin-ocm",";","Disabled" -"OCM","@backstage-community/plugin-ocm-backend","Backend","5.7.0","Production","active","./dynamic-plugins/dist/backstage-community-plugin-ocm-backend-dynamic","`OCM_HUB_NAME`;`OCM_HUB_URL`;`OCM_SA_TOKEN`;","Disabled" "Quay","@backstage-community/plugin-quay","Frontend","1.21.1","Production","active","./dynamic-plugins/dist/backstage-community-plugin-quay",";","Disabled" "Quay","@backstage-community/plugin-scaffolder-backend-module-quay","Backend","2.9.1","Production","active","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-quay-dynamic",";","Enabled" -"Quickstart","@red-hat-developer-hub/backstage-plugin-quickstart","Frontend","1.1.1","Production","active","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-quickstart",";","Enabled" +"Quickstart","@red-hat-developer-hub/backstage-plugin-quickstart","Frontend","1.6.2","Production","active","./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-quickstart",";","Enabled" "RBAC","@backstage-community/plugin-rbac","Frontend","1.42.0","Production","active","./dynamic-plugins/dist/backstage-community-plugin-rbac",";","Disabled" "Regex","@backstage-community/plugin-scaffolder-backend-module-regex","Backend","2.7.0","Production","active","./dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-regex-dynamic",";","Enabled" "Signals","@backstage/plugin-signals-backend","Backend","0.3.4","Production","active","./dynamic-plugins/dist/backstage-plugin-signals-backend-dynamic",";","Disabled" @@ -26,12 +24,12 @@ "Topology","@backstage-community/plugin-topology","Frontend","2.2.2","Production","active","./dynamic-plugins/dist/backstage-community-plugin-topology",";","Disabled" "3scale","@backstage-community/plugin-3scale-backend","Backend","3.6.1","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-community-plugin-3scale-backend-dynamic","`THREESCALE_ACCESS_TOKEN`;`THREESCALE_BASE_URL`;","Disabled" "ACR","@backstage-community/plugin-acr","Frontend","1.15.1","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-community-plugin-acr",";","Disabled" -"Argo CD (Red Hat)","@backstage-community/plugin-redhat-argocd","Frontend","1.21.2","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-community-plugin-redhat-argocd",";","Disabled" "Argo CD","@roadiehq/scaffolder-backend-argocd","Backend","1.6.0","Red Hat Tech Preview","active","./dynamic-plugins/dist/roadiehq-scaffolder-backend-argocd-dynamic","`ARGOCD_AUTH_TOKEN`;`ARGOCD_AUTH_TOKEN2`;`ARGOCD_INSTANCE1_URL`;`ARGOCD_INSTANCE2_URL`;`ARGOCD_PASSWORD`;`ARGOCD_USERNAME`;","Disabled" +"Argo CD (Red Hat)","@backstage-community/plugin-redhat-argocd","Frontend","1.25.1","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-community-plugin-redhat-argocd",";","Disabled" +"Azure","@backstage/plugin-scaffolder-backend-module-azure","Backend","0.2.9","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-azure-dynamic",";","Disabled" "Azure Devops","@backstage-community/plugin-azure-devops","Frontend","0.16.1","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-community-plugin-azure-devops",";","Disabled" "Azure Devops","@backstage-community/plugin-azure-devops-backend","Backend","0.17.1","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-community-plugin-azure-devops-backend-dynamic","`AZURE_ORG`;`AZURE_TOKEN`;","Disabled" "Azure Repositories","@parfuemerie-douglas/scaffolder-backend-module-azure-repositories","Backend","0.3.0","Red Hat Tech Preview","active","./dynamic-plugins/dist/parfuemerie-douglas-scaffolder-backend-module-azure-repositories-dynamic",";","Disabled" -"Azure","@backstage/plugin-scaffolder-backend-module-azure","Backend","0.2.9","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-azure-dynamic",";","Disabled" "Bitbucket Cloud","@backstage/plugin-catalog-backend-module-bitbucket-cloud","Backend","0.4.8","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-bitbucket-cloud-dynamic","`BITBUCKET_WORKSPACE`;","Disabled" "Bitbucket Cloud","@backstage/plugin-scaffolder-backend-module-bitbucket-cloud","Backend","0.2.9","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-bitbucket-cloud-dynamic",";","Disabled" "Bitbucket Server","@backstage/plugin-catalog-backend-module-bitbucket-server","Backend","0.4.1","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-bitbucket-server-dynamic","`BITBUCKET_HOST`;","Disabled" @@ -45,11 +43,11 @@ "GitHub Insights","@roadiehq/backstage-plugin-github-insights","Frontend","3.1.4","Red Hat Tech Preview","active","./dynamic-plugins/dist/roadiehq-backstage-plugin-github-insights",";","Disabled" "GitHub Issues","@backstage-community/plugin-github-issues","Frontend","0.10.0","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-community-plugin-github-issues",";","Disabled" "GitHub Pull Requests","@roadiehq/backstage-plugin-github-pull-requests","Frontend","3.4.2","Red Hat Tech Preview","active","./dynamic-plugins/dist/roadiehq-backstage-plugin-github-pull-requests",";","Disabled" -"GitLab Org","@backstage/plugin-catalog-backend-module-gitlab-org","Backend","0.2.9","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-org-dynamic",";","Disabled" "GitLab","@immobiliarelabs/backstage-plugin-gitlab","Frontend","6.12.1","Red Hat Tech Preview","active","./dynamic-plugins/dist/immobiliarelabs-backstage-plugin-gitlab",";","Disabled" "GitLab","@backstage/plugin-catalog-backend-module-gitlab","Backend","0.6.6","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-dynamic",";","Disabled" "GitLab","@immobiliarelabs/backstage-plugin-gitlab-backend","Backend","6.12.0","Red Hat Tech Preview","active","./dynamic-plugins/dist/immobiliarelabs-backstage-plugin-gitlab-backend-dynamic","`GITLAB_HOST`;`GITLAB_TOKEN`;","Disabled" "GitLab","@backstage/plugin-scaffolder-backend-module-gitlab","Backend","0.9.1","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-gitlab-dynamic",";","Disabled" +"GitLab Org","@backstage/plugin-catalog-backend-module-gitlab-org","Backend","0.2.9","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-org-dynamic",";","Disabled" "Http Request","@roadiehq/scaffolder-backend-module-http-request","Backend","5.3.4","Red Hat Tech Preview","active","./dynamic-plugins/dist/roadiehq-scaffolder-backend-module-http-request-dynamic",";","Disabled" "Jenkins","@backstage-community/plugin-jenkins","Frontend","0.20.0","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-community-plugin-jenkins",";","Disabled" "Jenkins","@backstage-community/plugin-jenkins-backend","Backend","0.15.0","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-community-plugin-jenkins-backend-dynamic","`JENKINS_TOKEN`;`JENKINS_URL`;`JENKINS_USERNAME`;","Disabled" @@ -78,3 +76,5 @@ "Tech Radar","@backstage-community/plugin-tech-radar","Frontend","1.7.1","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-community-plugin-tech-radar",";","Disabled" "Tech Radar","@backstage-community/plugin-tech-radar-backend","Backend","1.6.0","Red Hat Tech Preview","active","./dynamic-plugins/dist/backstage-community-plugin-tech-radar-backend-dynamic","`TECH_RADAR_DATA_URL`;","Disabled" "Utils","@roadiehq/scaffolder-backend-module-utils","Backend","3.5.0","Red Hat Tech Preview","active","./dynamic-plugins/dist/roadiehq-scaffolder-backend-module-utils-dynamic",";","Disabled" +"OCM","@backstage-community/plugin-ocm","Frontend","5.6.0","Production","deprecated","./dynamic-plugins/dist/backstage-community-plugin-ocm",";","Disabled" +"OCM","@backstage-community/plugin-ocm-backend","Backend","5.7.0","Production","deprecated","./dynamic-plugins/dist/backstage-community-plugin-ocm-backend-dynamic","`OCM_HUB_NAME`;`OCM_HUB_URL`;`OCM_SA_TOKEN`;","Disabled" diff --git a/modules/dynamic-plugins/rhdh-supported-plugins.sh b/modules/dynamic-plugins/rhdh-supported-plugins.sh index 31891144c4..2911c03de2 100755 --- a/modules/dynamic-plugins/rhdh-supported-plugins.sh +++ b/modules/dynamic-plugins/rhdh-supported-plugins.sh @@ -327,7 +327,9 @@ for y in $yamls; do csv_content="\"$PrettyName\",\"$Plugin\",\"$Role\",\"$Version\",\"$Support_Level\",\"$Lifecycle\",\"$Path\",\"${Required_Variables_CSV}\",\"$Default\"" # split into three tables based on support level - if [[ ${Support_Level} == "Production" ]]; then + if [[ ${Lifecycle} == "deprecated" ]]; then + echo "$key|$adoc_content" >> "$TEMP_DIR/adoc.deprecated.tmp" + elif [[ ${Support_Level} == "Production" ]]; then echo "$key|$adoc_content" >> "$TEMP_DIR/adoc.production.tmp" elif [[ ${Support_Level} == "Red Hat Tech Preview" ]]; then echo "$key|$adoc_content" >> "$TEMP_DIR/adoc.tech-preview.tmp" @@ -337,7 +339,9 @@ for y in $yamls; do # Group CSV by support level SupportSort=3 - if [[ ${Support_Level} == "Production" ]]; then + if [[ ${Lifecycle} == "deprecated" ]]; then + SupportSort=4 + elif [[ ${Support_Level} == "Production" ]]; then SupportSort=1 elif [[ ${Support_Level} == "Red Hat Tech Preview" ]]; then SupportSort=2 @@ -406,7 +410,22 @@ if [[ -f "$temp_file" ]]; then fi num_plugins+=($count) -# Process CSV: sort by SupportSort (1,2,3) then PrettyName, and omit techdocs +# 3) Deprecated +temp_file="$TEMP_DIR/adoc.deprecated.tmp" +out_file="${0/.sh/.ref-deprecated-plugins}" +rm -f "$out_file" +count=0 +if [[ -f "$temp_file" ]]; then + sort "$temp_file" | while IFS='|' read -r key content; do + (( count = count + 1 )) + if [[ $QUIET -eq 0 ]]; then echo " * [$count] $key [ ${out_file##*/} ]"; fi + echo -e "$content" >> "$out_file" + done + count=$(wc -l < "$temp_file") +fi +num_plugins+=($count) + +# Process CSV: sort by SupportSort (1,2,3,4) then PrettyName, and omit techdocs if [[ -f "$TEMP_DIR/csv.tmp" ]]; then sort -t '|' -k1,1 -k2,2 "$TEMP_DIR/csv.tmp" | while IFS='|' read -r key content; do # RHIDP-4196 omit techdocs plugins from the .csv @@ -420,10 +439,10 @@ fi if [[ $QUIET -eq 0 ]]; then echo; fi -# merge the content from the three .adocX files into the .template.adoc file, replacing the TABLE_CONTENT markers +# merge the content from the 4 .adocX files into the .template.adoc file, replacing the TABLE_CONTENT markers count=1 index=0 -for d in ref-rh-supported-plugins ref-rh-tech-preview-plugins ref-community-plugins; do +for d in ref-rh-supported-plugins ref-rh-tech-preview-plugins ref-community-plugins ref-deprecated-plugins; do (( index = count - 1 )) this_num_plugins=${num_plugins[$index]} echo -n -e "${green}[$count] Processing $d ${norm}..." diff --git a/modules/importing-repositories/procedure-enabling-the-bulk-import-from-github-feature.adoc b/modules/importing-repositories/procedure-enabling-the-bulk-import-from-github-feature.adoc index 97b22e44ba..cd908c0273 100644 --- a/modules/importing-repositories/procedure-enabling-the-bulk-import-from-github-feature.adoc +++ b/modules/importing-repositories/procedure-enabling-the-bulk-import-from-github-feature.adoc @@ -6,7 +6,7 @@ You can enable the Bulk Import feature for users and give them the necessary permissions to access it. .Prerequisites -* You have xref:enabling-github-repository-discovery[enabled GitHub repository discovery]. +* You have {integrating-with-github-book-link}#enabling-github-repository-discovery[enabled GitHub repository discovery]. .Procedure . The Bulk Import plugins are installed but disabled by default. diff --git a/modules/importing-repositories/procedure-managing-the-imported-repository-list.adoc b/modules/importing-repositories/procedure-managing-the-imported-repository-list.adoc index d80869b9a6..b2eae64aa1 100644 --- a/modules/importing-repositories/procedure-managing-the-imported-repository-list.adoc +++ b/modules/importing-repositories/procedure-managing-the-imported-repository-list.adoc @@ -26,7 +26,7 @@ Empty:: {product-short} is unable to determine the import job status because the [NOTE] ==== * After an import pull request is merged, the import status is marked as _Added_ in the list of Added Repositories, but it might take a few seconds for the corresponding entities to appear in the {product-short} Catalog. -* A location added through other sources (like statically in an `{my-app-config-file}` file, dynamically when xref:enabling-github-repository-discovery[enabling GitHub discovery], or registered manually using the "Register an existing component" page) might show up in the Bulk Import list of Added Repositories if the following conditions are met: +* A location added through other sources (like statically in an `{my-app-config-file}` file, dynamically when {integrating-with-github-book-link}#enabling-github-repository-discovery[enabling GitHub discovery], or registered manually using the "Register an existing component" page) might show up in the Bulk Import list of Added Repositories if the following conditions are met: ** The target repository is accessible from the configured GitHub integrations. ** The location URL points to a `catalog-info.yaml` file at the root of the repository default branch. ==== diff --git a/modules/installation/proc-install-operator.adoc b/modules/installation/proc-install-operator.adoc index 2a27a51312..0af215e6fe 100644 --- a/modules/installation/proc-install-operator.adoc +++ b/modules/installation/proc-install-operator.adoc @@ -14,7 +14,7 @@ Containers are available for the following CPU architectures: * You are logged in as an administrator on the {ocp-short} web console. * You have configured the appropriate roles and permissions within your project to create or access an application. For more information, see the {ocp-docs-link}/html-single/building_applications/index#building-applications-overview[{ocp-brand-name} documentation on Building applications]. * You have installed {ocp-brand-name} {ocp-version-min} to {ocp-version}. -* Make sure that your system meets the minimum sizing requirements. See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.7/html-single/about_red_hat_developer_hub/index#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. +* Make sure that your system meets the minimum sizing requirements. See {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. .Procedure @@ -82,8 +82,3 @@ If you selected an *Automatic* approval strategy, the upgrade status should reso *** From the list of installed Operators, locate the {product} Operator name and details. *** Click *{product} Operator* to open the *Operator details* page for the {product} Operator. -[role="_additional-resources"] -.Additional resources - -* xref:proc-install-rhdh-ocp-operator_{context}[Deploying {product} on {ocp-short} with the Operator] -* {ocp-docs-link}/html-single/operators/index#olm-installing-from-operatorhub-using-web-console_olm-adding-operators-to-a-cluster[Installing from OperatorHub by using the web console] diff --git a/modules/installation/proc-install-rhdh-airgapped-partial-k8s-helm.adoc b/modules/installation/proc-install-rhdh-airgapped-partial-k8s-helm.adoc index 1027b0da6f..8aab402d21 100644 --- a/modules/installation/proc-install-rhdh-airgapped-partial-k8s-helm.adoc +++ b/modules/installation/proc-install-rhdh-airgapped-partial-k8s-helm.adoc @@ -19,7 +19,7 @@ In a partially disconnected environment, the cluster cannot access external regi . In a terminal, download and extract the Helm chart by running the following commands: + -[source,terminal,subs="attributes+"] +[source,terminal,subs="+attributes,+quotes"] ---- helm repo add __ https://charts.openshift.io/ helm repo update @@ -27,10 +27,10 @@ helm pull __/redhat-developer-hub --version __/redhat-developer-hub --version __ > values.default.yaml ---- + -where +where: -__ :: Specifies the name of the Helm chart repository, for example, `openshift-helm-charts`. -__ :: Specifies the {product} version that you want to use, for example, `{product-chart-version}`. +__ :: Enter the name of the Helm chart repository, for example, `openshift-helm-charts`. +__ :: Enter the {product} version that you want to use, for example, `{product-chart-version}`. + . Use `yq` to extract the image digests by running the following commands: + diff --git a/modules/installation/proc-install-rhdh-helm-airgapped-full.adoc b/modules/installation/proc-install-rhdh-helm-airgapped-full.adoc index 4350cf146e..b7fdf1c048 100644 --- a/modules/installation/proc-install-rhdh-helm-airgapped-full.adoc +++ b/modules/installation/proc-install-rhdh-helm-airgapped-full.adoc @@ -8,38 +8,36 @@ If your network has access to the registry through a bastion host, you can use t .Prerequisites * You have set up your workstation. -** You have access to the registry.redhat.io. +** You have an account in https://developers.redhat.com/[{rhdeveloper-name}] portal. ** You have access to the charts.openshift.io Helm chart repository. ** You have installed the {openshift-cli} on your workstation. -* {ocp-docs-link}/html-single/disconnected_environments/index#about-installing-oc-mirror-v2[You have installed the oc-mirror OpenShift CLI plugin]. -** You have an account in https://developers.redhat.com/[{rhdeveloper-name}] portal. -** You have set up your intermediary host. -** Your host has access to the disconnected cluster and to the target mirror registry, for example, the {ocp-brand-name} image registry. For more information about exposing the {ocp-short} image registry, see {ocp-docs-link}/html-single/registry/index#securing-exposing-registry[Exposing the registry]. -** {ocp-docs-link}/html-single/disconnected_environments/index#about-installing-oc-mirror-v2[You have installed the oc-mirror OpenShift CLI plugin]. +** You have installed the {ocp-docs-link}/html-single/disconnected_environments/index#installation-oc-mirror-installing-plugin_about-installing-oc-mirror-v2[`oc-mirror`] tool, with a version corresponding to the version of your {ocp-short} cluster. +* You have set up your intermediary host. +** Your host has access to the link:https://registry.redhat.io[{company-name} Ecosystem Catalog]. +** Your host has access to image registry on the destination host. +See {ocp-docs-link}/html-single/registry/index#securing-exposing-registry[Exposing the registry]. +* You have set up your destination host. ** You have installed {ocp-brand-name} {ocp-version-min} or later. -** You have installed the {openshift-cli} on your workstation. -* Make sure that your system meets the minimum sizing requirements. See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.7/html-single/about_red_hat_developer_hub/index#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. +** Your system meets the minimum sizing requirements. See {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. .Procedure . Create an `ImageSetConfiguration` file to specify the resources that you want to mirror. For example: + -[source,terminal,subs="+quotes"] +[source,yaml,subs="+attributes,+quotes"] ---- apiVersion: mirror.openshift.io/v1alpha2 kind: ImageSetConfiguration mirror: helm: repositories: - - name: __ (1) - url: __ (2) + - name: openshift-charts + url: https://charts.openshift.io charts: - - name: __ (3) - version: "__" (4) + - name: redhat-developer-hub + version: "{product-version}" ---- -<1> The name of the repository that you want to mirror, for example, `openshift-charts`. -<2> The URL for the repository that you want to mirror, for example, `https://charts.openshift.io`. -<3> The name of the Helm chart that you want to mirror, for example, `redhat-developer-hub`. -<4> The version of {product} that you want to use, for example, `{product-version}` +where: +`version: "{product-version}"`:: Enter the {product} version to mirror. . Mirror the resources specified in the `ImageSetConfiguration.yaml` file by running the `oc-mirror` command. For example: + @@ -51,11 +49,9 @@ oc-mirror --config=__/ImageSetConfiguration.yaml _` :: Specifies the location of your image set configuration file on your system, for example, `.user`. +`` :: Enter the location of your image set configuration file on your system, for example, `.user`. -`` :: Specifies the name of your mirror configuration yaml file, for example, `mirror-config.yaml` - -`` :: Specifies the location of your directory where the mirror archive will be created, for example, `pass:[file://.user]`. +`` :: Enter the location of your directory where the mirror archive will be created, for example, `pass:[file://.user]`. -- + [NOTE] @@ -63,7 +59,8 @@ where: Running the `oc-mirror` command generates a local workspace containing the mirror archive file, the Helm chart, and a `ImageContentSourcePolicy` (ICSP) manifest. The ICSP manifest contains an `imageContentSourcePolicy.yaml` file that you must apply against the cluster in a later step. ==== + -.Example output +Example output: ++ [source,terminal,subs="+quotes"] ---- Creating archive /path/to/mirror-archive/mirror_seq1_000000.tar @@ -85,9 +82,9 @@ oc-mirror --from __ __ -- where: -`` :: Specifies the name of the file containing the resources that you want to mirror, for example,`mirror_seq1_0000.tar`. +`` :: Enter the name of the file containing the resources that you want to mirror, for example,`mirror_seq1_0000.tar`. -`` :: Specifies the name of the target registry that you want to push the mirrored images to, for example, `docker://registry.localhost:5000`. +`` :: Enter the name of the target registry that you want to push the mirrored images to, for example, `docker://registry.localhost:5000`. -- + .Example output @@ -123,9 +120,9 @@ oc apply -f __/__/ImageContentSourcePoli -- where: -`` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. +`` :: Enter the name of your workspace directory, for example, `oc-mirror-workspace`. -`` :: Specifies the name of your results directory, for example, `results-1738070846`. +`` :: Enter the name of your results directory, for example, `results-1738070846`. -- . In your air-gapped environment, deploy the Helm chart to the namespace that you want to use by running the `helm install` command with `namespace` and `set` options. For example: + @@ -140,13 +137,13 @@ helm install __ __/__/cha -- where: -`` :: Specifies the name of your {product} instance, for example, `my-rhdh`. +`` :: Enter the name of your {product} instance, for example, `{my-product-namespace}`. -`` :: Specifies the name of your workspace directory, for example, `oc-mirror-workspace`. +`` :: Enter the name of your workspace directory, for example, `oc-mirror-workspace`. -`` :: Specifies the name of your results directory, for example, `results-1738070846`. +`` :: Enter the name of your results directory, for example, `results-1738070846`. -`` :: Specifies the name of the archive file containing the resources that you want to mirror, for example, `redhat-developer-hub-1.4.1.tgz`. +`` :: Enter the name of the archive file containing the resources that you want to mirror, for example, `redhat-developer-hub-1.4.1.tgz`. -`` :: Specifies the namespace that you want to deploy the Helm chart to, for example, `{my-product-namespace}`. +`` :: Enter the namespace that you want to deploy the Helm chart to, for example, `{my-product-namespace}`. -- diff --git a/modules/installation/proc-install-rhdh-helm-airgapped-partial.adoc b/modules/installation/proc-install-rhdh-helm-airgapped-partial.adoc index db023a0bee..d4516ef8dd 100644 --- a/modules/installation/proc-install-rhdh-helm-airgapped-partial.adoc +++ b/modules/installation/proc-install-rhdh-helm-airgapped-partial.adoc @@ -13,9 +13,9 @@ If your network has access to the `registry.redhat.io` registry and the `charts. * You have access to a mirror registry that can be reached from the disconnected cluster, for example, the {ocp-short} image registry. For more information about exposing the {ocp-short} image registry, see {ocp-docs-link}/html-single/registry/index#securing-exposing-registry[Exposing the registry]. * You are logged in to your target mirror registry and have permissions to push images to it. For more information, see {ocp-docs-link}/html-single/disconnected_environments/index#installation-adding-registry-pull-secret_about-installing-oc-mirror-v2[Configuring credentials that allow images to be mirrored]. * You have installed the {openshift-cli} on your workstation. -* {ocp-docs-link}/html-single/disconnected_environments/index#about-installing-oc-mirror-v2[You have installed the oc-mirror OpenShift CLI plugin]. +* Recommended on {ocp-short}: You have installed the {ocp-docs-link}/html-single/disconnected_environments/index#installation-oc-mirror-installing-plugin_about-installing-oc-mirror-v2[`oc-mirror`] tool, with a version corresponding to the version of your {ocp-short} cluster. * You have an account in https://developers.redhat.com/[{rhdeveloper-name}] portal. -* Make sure that your system meets the minimum sizing requirements. See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.7/html-single/about_red_hat_developer_hub/index#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. +* Make sure that your system meets the minimum sizing requirements. See {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. .Procedure . Log in to your {ocp-short} account using the {openshift-cli} by running the following command: @@ -29,23 +29,20 @@ oc login -u -p https://api.:6443 . Create an `ImageSetConfiguration.yaml` file. . In your `ImageSetConfiguration.yaml` file, specify the resources that you want to mirror. For example: + -[source,terminal,subs="+quotes"] +[source,yaml,subs="+attributes,+quotes"] ---- apiVersion: mirror.openshift.io/v1alpha2 kind: ImageSetConfiguration mirror: helm: repositories: - - name: __ (1) - url: __ (2) + - name: openshift-charts + url: https://charts.openshift.io charts: - - name: __ (3) - version: "__" (4) + - name: redhat-developer-hub + version: "{product-version}" ---- -<1> The name of the repository containing the Helm chart that you want to mirror, for example, `openshift-charts`. -<2> The URL for the repository containing the Helm chart that you want to mirror, for example, `https://charts.openshift.io`. -<3> The name of the Helm chart containing the images that you want to mirror, for example, `redhat-developer-hub`. -<4> The {product} version that you want to use, for example, `{product-version}` +`version: "{product-version}"`:: Enter the {product} version to mirror. . Mirror the resources specified in the image set configuration file directly to the target registry by running the `oc-mirror` command. For example: + diff --git a/modules/installation/proc-install-rhdh-ocp-helm-gui.adoc b/modules/installation/proc-install-rhdh-ocp-helm-gui.adoc index 371804cd03..69b5223ba9 100644 --- a/modules/installation/proc-install-rhdh-ocp-helm-gui.adoc +++ b/modules/installation/proc-install-rhdh-ocp-helm-gui.adoc @@ -19,7 +19,7 @@ The {product} Helm chart is available in the Helm catalog on {osd-short} and {oc * You are logged in to your {ocp-short} account. * A user with the {ocp-short} `admin` role has configured the appropriate roles and permissions within your project to create an application. For more information about {ocp-short} roles, see {ocp-docs-link}/html-single/authentication_and_authorization/index#authorization-overview_using-rbac[Using RBAC to define and apply permissions]. * You have created a project in {ocp-short}. For more information about creating a project in {ocp-short}, see {ocp-docs-link}/html-single/building_applications/index#working-with-projects[{ocp-brand-name} documentation]. -* Make sure that your system meets the minimum sizing requirements. See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.7/html-single/about_red_hat_developer_hub/index#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. +* Make sure that your system meets the minimum sizing requirements. See {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. .Procedure diff --git a/modules/installation/proc-install-rhdh-operator-airgapped-full.adoc b/modules/installation/proc-install-rhdh-operator-airgapped-full.adoc index 546d2fa398..ba8c2fb17e 100644 --- a/modules/installation/proc-install-rhdh-operator-airgapped-full.adoc +++ b/modules/installation/proc-install-rhdh-operator-airgapped-full.adoc @@ -16,27 +16,29 @@ If your network has access to the registry through a bastion host, you can use t * You have installed `umoci` CLI tool. * You have an active `oc registry`, `podman`, or `skopeo` session to the `registry.redhat.io` {company-name} Ecosystem Catalog. For more information, see link:link:https://access.redhat.com/articles/RegistryAuthentication[{company-name} Container Registry Authentication]. * You have installed the `opm` CLI tool. For more information, see {ocp-docs-link}/html/cli_tools/opm-cli#olm-about-opm_cli-opm-install[Installing the opm CLI]. -* Make sure that your system meets the minimum sizing requirements. See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.7/html-single/about_red_hat_developer_hub/index#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. +* Recommended on {ocp-short}: You have installed the {ocp-docs-link}/html-single/disconnected_environments/index#installation-oc-mirror-installing-plugin_about-installing-oc-mirror-v2[`oc-mirror`] tool, with a version corresponding to the version of your {ocp-short} cluster. +* Make sure that your system meets the minimum sizing requirements. See {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. .Procedure . Download the mirroring script to disk by running the following command: + -[source,terminal,subs="attributes+"] +[source,terminal,subs="+attributes,+quotes"] ---- curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-{product-version}/.rhdh/scripts/prepare-restricted-environment.sh ---- + . Run the mirroring script by using the `bash` command with the appropriate set of options: + -[source,terminal,subs="attributes+"] +[source,terminal,subs="+attributes,+quotes"] ---- bash prepare-restricted-environment.sh --filter-versions "{product-version}" - --to-dir __ <1> - [--use-oc-mirror true] <2> + --to-dir __ + [--use-oc-mirror true] ---- -<1> Specifies the absolute path to a directory where you want to pull all of the necessary images with the `--to-dir` option, for example, `/home/user/rhdh-operator-mirror-dir`. -<2> (Optional) Uses the `oc-mirror` {ocp-short} CLI plugin to mirror images. +where: +`--to-dir __`:: Enter the absolute path to a directory where you want to pull all of the necessary images, for example, `/home/user/rhdh-operator-mirror-dir`. +`--use-oc-mirror true`:: (Recommended on {ocp-short}) Use the `oc-mirror` {ocp-short} CLI plugin to mirror images. + [NOTE] ==== @@ -48,15 +50,16 @@ The script can take several minutes to complete as it copies multiple images to + [source,terminal,subs="+quotes,+attributes"] ---- -bash __/install.sh <1> - --from-dir __ <2> - [--to-registry __] <3> - [--use-oc-mirror true] <4> +bash __/install.sh + --from-dir __ + [--to-registry __] + [--use-oc-mirror true] ---- -<1> The downloaded image and the absolute path to the directory where it is stored on your system. -<2> Specifies the directory where you want to pull all of the necessary images with the `--to-dir` option. -<3> Specifies the URL for the target mirror registry where you want to mirror the images. -<4> (Optional) Uses the `oc-mirror` {ocp-short} CLI plugin to mirror images. +where: +`__/install.sh`:: Enter the downloaded installation script and the absolute path to the directory where it is stored on your system. +`--from-dir __`:: Enter the directory where you want to pull all of the necessary images. +`--to-registry`:: (Optional) Enter the URL for the target mirror registry where you want to mirror the images. +`--use-oc-mirror true`:: Recommended on {ocp-short}: Use the `oc-mirror` {ocp-short} CLI plugin to mirror images. + [IMPORTANT] ==== diff --git a/modules/installation/proc-install-rhdh-operator-airgapped-partial.adoc b/modules/installation/proc-install-rhdh-operator-airgapped-partial.adoc index e7495a980b..49474a7b9f 100644 --- a/modules/installation/proc-install-rhdh-operator-airgapped-partial.adoc +++ b/modules/installation/proc-install-rhdh-operator-airgapped-partial.adoc @@ -3,32 +3,42 @@ [id="proc-install-rhdh-operator-airgapped-partial.adoc_{context}"] = Installing {product} in a partially disconnected environment with the Operator -On an {ocp-short} cluster operating on a restricted network, public resources are not available. However, deploying the {product} Operator and running {product-short} requires the following public resources: +On an {ocp-short} cluster operating on a restricted network, public resources are not available. +However, deploying the {product} Operator and running {product-short} requires the following public resources: * Operator images (bundle, operator, catalog) * Operands images ({product-very-short}, PostgreSQL) To make these resources available, replace them with their equivalent resources in a mirror registry accessible to your cluster. -You can use a helper script that mirrors the necessary images and provides the necessary configuration to ensure those images are used when installing the {product} Operator and creating {product-short} instances. This script requires a target mirror registry. You likely have a target mirror registry if your cluster is already operating on a disconnected network. If you do not already have a target registry, and if you have an {ocp-short} cluster, you might want to expose and leverage the internal cluster registry. +You can use a helper script that mirrors the necessary images and provides the necessary configuration to ensure those images are used when installing the {product} Operator and creating {product-short} instances. +This script requires a target mirror registry. +You likely have a target mirror registry if your cluster is already operating on a disconnected network. +If you do not already have a target registry, and if you have an {ocp-short} cluster, you might want to expose and leverage the internal cluster registry. -When connected to a {ocp-short} cluster, the helper script detects it and automatically exposes the cluster registry. If connected to a Kubernetes cluster, you can manually specify the target registry to mirror the images. +When connected to a {ocp-short} cluster, the helper script detects it and automatically exposes the cluster registry. +If connected to a Kubernetes cluster, you can manually specify the target registry to mirror the images. .Prerequisites -* You have installed Podman 5.3 or later. For more information, see link:https://podman.io/docs/installation[Podman Installation Instructions]. +* You have installed Podman 5.3 or later. +For more information, see link:https://podman.io/docs/installation[Podman Installation Instructions]. * You have installed Skopeo 1.17 or later. * You have installed `yq` 4.44 or later. * You have installed the GNU `sed` command line text editor. * You have installed `umoci` CLI tool. -* You have an active `oc registry`, `podman`, or `skopeo` session to the `registry.redhat.io` {company-name} Ecosystem Catalog. For more information, see link:link:https://access.redhat.com/articles/RegistryAuthentication[{company-name} Container Registry Authentication]. -* You have an active `skopeo` session with administrative access to the target mirror registry. For more information, see link:https://github.com/containers/skopeo#authenticating-to-a-registry[Authenticating to a registry]. -* You have installed the `opm` CLI tool. For more information, see {ocp-docs-link}/html/cli_tools/opm-cli#olm-about-opm_cli-opm-install[Installing the opm CLI]. +* You have an active `oc registry`, `podman`, or `Skopeo` session to the `registry.redhat.io` {company-name} Ecosystem Catalog. +For more information, see link:link:https://access.redhat.com/articles/RegistryAuthentication[{company-name} Container Registry Authentication]. +* You have an active `Skopeo` session with administrative access to the target mirror registry. +For more information, see link:https://github.com/containers/skopeo#authenticating-to-a-registry[Authenticating to a registry]. +* You have installed the `opm` CLI tool. +For more information, see {ocp-docs-link}/html/cli_tools/opm-cli#olm-about-opm_cli-opm-install[Installing the opm CLI]. * If you are using an {ocp-short} cluster, you have the following prerequisites: -** (Optional) You have installed the `oc-mirror` {ocp-short} CLI plugin if you want to use it to mirror images. +** Recommended: You have installed the `oc-mirror` tool, with a version corresponding to the version of your {ocp-short} cluster. * If you are using a supported Kubernetes cluster, you have the following prerequisites: ** You have installed the Operator Lifecycle Manager (OLM) on the disconnected cluster. ** You have a mirror registry that is reachable from the disconnected cluster. -* Make sure that your system meets the minimum sizing requirements. See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.7/html-single/about_red_hat_developer_hub/index#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. +* Make sure that your system meets the minimum sizing requirements. +See {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. .Procedure . In your terminal, navigate to the directory where you want to save the mirroring script. @@ -45,11 +55,12 @@ curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs ---- bash prepare-restricted-environment.sh \ --filter-versions "{product-version}" \ - [--to-registry __] \ <1> - [--use-oc-mirror true] <2> + [--to-registry __] \ + [--use-oc-mirror true] ---- -<1> Specifies the URL for the target mirror registry where you want to mirror the images. -<2> (Optional) Uses the `oc-mirror` {ocp-short} CLI plugin to mirror images. +where: +`--to-registry _`:: Enter the URL for the target mirror registry where you want to mirror the images. +`--use-oc-mirror true`:: Optional: Use the `oc-mirror` {ocp-short} CLI plugin to mirror images. + [NOTE] ==== @@ -66,7 +77,8 @@ kubectl -n rhdh-operator get pods ---- .Next steps -* Use the Operator to create a {product} instance on a supported platform. For more information, see the following documentation for the platform that you want to use: +* Use the Operator to create a {product} instance on a supported platform. +For more information, see the following documentation for the platform that you want to use: ** {installing-on-ocp-book-link}#assembly-install-rhdh-ocp-operator[Installing {product} on {ocp-short} with the Operator] ** {installing-on-eks-book-link}#assembly-install-rhdh-eks-operator[Installing {product-short} on {eks-short} with the Operator] ** {installing-on-aks-book-link}#proc-rhdh-deploy-aks-operator_title-install-rhdh-aks[Installing {product-short} on {aks-short} with the Operator] diff --git a/modules/installation/proc-install-rhdh-osd-gcp-helm.adoc b/modules/installation/proc-install-rhdh-osd-gcp-helm.adoc index b9229718cb..dd31ed9e92 100644 --- a/modules/installation/proc-install-rhdh-osd-gcp-helm.adoc +++ b/modules/installation/proc-install-rhdh-osd-gcp-helm.adoc @@ -9,7 +9,7 @@ You can install {product-short} on {osd-short} on {gcp-short} using the {product * You have a valid {gcp-short} account. * Your {osd-short} cluster is running on {gcp-short}. For more information, see{osd-docs-link}/html/installing_accessing_and_deleting_openshift_dedicated_clusters/osd-creating-a-cluster-on-gcp[Creating a cluster on GCP] in {osd-brand-name} documentation. * You have installed Helm 3 or the latest. -* Make sure that your system meets the minimum sizing requirements. See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.7/html-single/about_red_hat_developer_hub/index#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. +* Make sure that your system meets the minimum sizing requirements. See {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. .Procedure . From the *Developer* perspective on the {product-short} web console, click *+Add*. diff --git a/modules/installation/proc-install-rhdh-osd-gcp-operator.adoc b/modules/installation/proc-install-rhdh-osd-gcp-operator.adoc index e9dd677b17..3e0cd70d9e 100644 --- a/modules/installation/proc-install-rhdh-osd-gcp-operator.adoc +++ b/modules/installation/proc-install-rhdh-osd-gcp-operator.adoc @@ -9,7 +9,7 @@ You can install {product-short} on {osd-short} on {gcp-short} using the {product * You have a valid {gcp-short} account. * Your {osd-short} cluster is running on {gcp-short}. For more information, see{osd-docs-link}/html/installing_accessing_and_deleting_openshift_dedicated_clusters/osd-creating-a-cluster-on-gcp[Creating a cluster on GCP] in {osd-brand-name} documentation. * You have administrator access to {osd-short} cluster and {gcp-short} project. -* Make sure that your system meets the minimum sizing requirements. See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.7/html-single/about_red_hat_developer_hub/index#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. +* Make sure that your system meets the minimum sizing requirements. See {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. .Procedure diff --git a/modules/installation/proc-rhdh-deploy-aks-helm.adoc b/modules/installation/proc-rhdh-deploy-aks-helm.adoc index fff9a67def..137ed300d4 100644 --- a/modules/installation/proc-rhdh-deploy-aks-helm.adoc +++ b/modules/installation/proc-rhdh-deploy-aks-helm.adoc @@ -12,7 +12,7 @@ You can deploy your {product-short} application on {aks-name} ({aks-short}) to a * You have installed the link:https://kubernetes.io/docs/reference/kubectl/[`kubectl` CLI]. * You are logged into your cluster using `kubectl`, and have `developer` or `admin` permissions. * You have installed Helm 3 or the latest. -* Make sure that your system meets the minimum sizing requirements. See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.7/html-single/about_red_hat_developer_hub/index#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. +* Make sure that your system meets the minimum sizing requirements. See {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. .Comparison of {aks-short} specifics with the base {product-short} deployment diff --git a/modules/installation/proc-rhdh-deploy-eks-helm.adoc b/modules/installation/proc-rhdh-deploy-eks-helm.adoc index ac8c9b6c23..89afc6fffd 100644 --- a/modules/installation/proc-rhdh-deploy-eks-helm.adoc +++ b/modules/installation/proc-rhdh-deploy-eks-helm.adoc @@ -14,7 +14,7 @@ When you install the {product-short} Helm chart in {eks-name} ({eks-short}), it * You have set the context to the {eks-short} cluster in your current `kubeconfig`. For more information, see https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html[Creating or updating a kubeconfig file for an Amazon {eks-short} cluster]. * You have installed `kubectl`. For more information, see https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html[Installing or updating kubectl]. * You have installed Helm 3 or the latest. For more information, see https://docs.aws.amazon.com/eks/latest/userguide/helm.html[Using Helm with Amazon {eks-short}]. -* Make sure that your system meets the minimum sizing requirements. See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.7/html-single/about_red_hat_developer_hub/index#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. +* Make sure that your system meets the minimum sizing requirements. See {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. .Procedure diff --git a/modules/installation/proc-rhdh-deploy-gke-helm.adoc b/modules/installation/proc-rhdh-deploy-gke-helm.adoc index 578fe3d148..a428d38785 100644 --- a/modules/installation/proc-rhdh-deploy-gke-helm.adoc +++ b/modules/installation/proc-rhdh-deploy-gke-helm.adoc @@ -13,7 +13,7 @@ When you install the {product-short} Helm chart in {gke-brand-name} ({gke-short} * You have configured a domain name for your {product-short} instance. * You have reserved a static external Premium IPv4 Global IP address that is not attached to any VM. For more information see https://cloud.google.com/vpc/docs/reserve-static-external-ip-address#reserve_new_static[Reserve a new static external IP address] * You have configured the DNS records for your domain name to point to the IP address that has been reserved. -* Make sure that your system meets the minimum sizing requirements. See link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.7/html-single/about_red_hat_developer_hub/index#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. +* Make sure that your system meets the minimum sizing requirements. See {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for {product}]. + [NOTE] ==== diff --git a/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc b/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc index 1eec0663b6..5cfef2a18f 100644 --- a/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc +++ b/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc @@ -11,6 +11,8 @@ If a repository contains a `catalog-info.yaml` file, {product-short} ingests the * You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App]. +* To allow users to access GitHub templates or plugins that require GitHub authentication, you have configured GitHub either {authentication-book-link}#enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider[as an auxiliary authentication provider] or {authentication-book-link}#enabling-user-authentication-with-github[as your main authentication provider]. + .Procedure . To allow {product-short} to access the GitHub API, create a GitHub App. Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, gain more control over which repositories the application can access, and use short-lived tokens. diff --git a/modules/orchestrator/con-architecture-overview.adoc b/modules/orchestrator/con-architecture-overview.adoc new file mode 100644 index 0000000000..1990dfb9f1 --- /dev/null +++ b/modules/orchestrator/con-architecture-overview.adoc @@ -0,0 +1,36 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-architecture-overview.adoc_{context}"] += Understand Orchestrator architecture + +The Orchestrator architecture is composed of several components, each contributing to the running and management of workflows. + +{product} ({product-very-short}):: Serves as the primary interface. It contains the following subcomponents: + +Orchestrator frontend plugins::: Provide the interface for users to run and monitor workflows within {product-very-short}. + +Orchestrator backend plugins::: Get workflow data into {product-short}. + +Notifications plugins::: Inform users about workflow events. + +Sonataflow:: + +The Sonataflow orchestrator and its subcomponents handle the workflows. +The {product} Orchestrator and the {product} Helm chart manage the following subcomponents lifecycle: + +OpenShift Serverless Logic Operator::: Manages the Sonataflow custom resource (CR), where each CR represents a deployed workflow. + +Sonataflow Runtime/Workflow Application::: Functions as a deployed workflow. Operates as an HTTP server, handling requests for running workflow instances. It is managed as a Kubernetes (K8s) deployment by the Openshift Serverless Logic Operator. + +Data Index Service::: Serves as a repository for workflow definitions, instances, and associated jobs. It exposes a GraphQL API used by the Orchestrator backend plugin to retrieve workflow definitions and instances. +Job Service::: Orchestrates scheduled tasks for workflows. + +OpenShift Serverless::: Provides serverless capabilities essential for workflow communication. It employs Knative eventing to interface with the Data Index service and uses Knative functions to introduce more complex logic to workflows. + +PostgreSQL Server::: Provides a database solution essential for data persistence within the Orchestrator ecosystem. The system uses PostgreSQL Server for storing both Sonataflow information and {product-short} data. + +Keycloak:: Provides authentication and security services within applications. Keycloak must be provisioned externally to manage authentication, as the Orchestrator Operator does not install it. + +OpenShift AMQ Streams (Strimzi/Kafka):: Provides enhanced reliability of the eventing system. Eventing can work without Kafka by using direct HTTP calls, however, this approach is not reliable. ++ +Optional: The current deployment iteration does not natively integrate or include the AMQ Streams Operator. However, you can add the Operator post-install for enhanced reliability if you require it. \ No newline at end of file diff --git a/modules/orchestrator/con-benefits-of-workflow-images.adoc b/modules/orchestrator/con-benefits-of-workflow-images.adoc new file mode 100644 index 0000000000..743c7e31ed --- /dev/null +++ b/modules/orchestrator/con-benefits-of-workflow-images.adoc @@ -0,0 +1,11 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-benefits-of-workflow-images.adoc_{context}"] += Benefits of workflow images + +While the OpenShift Serverless Logic Operator supports the building of workflows dynamically, this approach is primarily for experimentation. +For production deployments, building images is the preferred method due to the following reasons: + +* Production readiness: Prebuilt images can be scanned, secured, and tested before going live. +* GitOps compatibility: The Orchestrator relies on a central OpenShift Serverless Logic Operator instance to track workflows and their state. To use this tracking service, you must deploy workflows with the `gitops` profile, which expects a prebuilt image. +* Testing and quality: Building an image gives you more control over the testing process. \ No newline at end of file diff --git a/modules/orchestrator/con-build-sh-script-and-its-uses.adoc b/modules/orchestrator/con-build-sh-script-and-its-uses.adoc new file mode 100644 index 0000000000..45ce77b4e3 --- /dev/null +++ b/modules/orchestrator/con-build-sh-script-and-its-uses.adoc @@ -0,0 +1,35 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-build-sh-script-and-its-uses.adoc_{context}"] += The `build-sh` script functionality and important flags + +The `build-sh` script does the following tasks in order: + +* Generates workflow manifests using the `kn-workflow` CLI. +* Builds the workflow image using `podman` or `docker`. +* Optional: The script pushes the images to an image registry and deploys the workflow using `kubectl`. + +You can review the script configuration options and see available flags and their functions by accessing the help menu: + +[source,bash] +---- +./scripts/build.sh [flags] +---- + +The following flags are essential for running the script: + +[cols="1,3", options="header"] +|=== +|Flag |Description +|`-i`, `--image` |Required: Full image path, for example, `quay.io/orchestrator/demo:latest` +|`-w`, `--workflow-directory` |Workflow source directory (default is the current directory) +|`-m`, `--manifests-directory` |Where to save generated manifests +|`--push` |Push the image to the registry +|`--deploy` |Deploy the workflow +|`-h`, `--help` |Show the help message +|=== + +[TIP] +==== +The script also supports builder and runtime image overrides, namespace targeting, and persistence flags. +==== \ No newline at end of file diff --git a/modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc b/modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc new file mode 100644 index 0000000000..d114fc18ab --- /dev/null +++ b/modules/orchestrator/con-environment-variables-supported-by-the-build-script.adoc @@ -0,0 +1,28 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-environment-variables-supported-by-the-build-script.adoc_{context}"] += Environment variables supported by the build script + +The `build-sh` script supports the following environment variables to customize the workflow build process without modifying the script itself: + +`QUARKUS_EXTENSIONS`:: + +The `QUARKUS_EXTENSIONS` variable specifies additional link:https://quarkus.io/extensions/[Quarkus] extensions required by the workflow. This variable takes the format of a comma-separated list of fully qualified extension IDs as shown in the following example: ++ +[source,yaml] +---- +export QUARKUS_EXTENSIONS="io.quarkus:quarkus-smallrye-reactive-messaging-kafka" +---- ++ +Add Kafka messaging support or other integrations at build time. + +`MAVEN_ARGS_APPEND`:: + +The `MAVEN_ARGS_APPEND` variable appends additional arguments to the *Maven build* command. This variable takes the format of a string of Maven CLI arguments as shown in the following example: ++ +[source,yaml] +---- +export MAVEN_ARGS_APPEND="-DmaxYamlCodePoints=35000000" +---- ++ +Control build behavior. For example, set `maxYamlCodePoints` parameter that controls the maximum input size for YAML input files to 35000000 characters (~33MB in UTF-8). \ No newline at end of file diff --git a/modules/orchestrator/con-generated-workflow-manifests.adoc b/modules/orchestrator/con-generated-workflow-manifests.adoc new file mode 100644 index 0000000000..5315700804 --- /dev/null +++ b/modules/orchestrator/con-generated-workflow-manifests.adoc @@ -0,0 +1,76 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-generated-workflow-manifests.adoc_{context}"] += Generated workflow manifests + +The following example is an illustration of what is generated under the `01_basic/manifests`: + +[source,yaml] +---- +01_basic/manifests +├── 00-secret_basic-secrets.yaml +├── 01-configmap_basic-props.yaml +├── 02-configmap_01-basic-resources-schemas.yaml +└── 03-sonataflow_basic.yaml +---- + +`00-secret_basic-secrets.yaml`:: +Contains secrets from `01_basic/src/main/resources/secret.properties`. +Values are not required at this stage as you can set them later after applying CRs or when using GitOps. + +[Important] +==== +In OpenShift Serverless Logic `v1.36`, after updating a secret, you must manually restart the workflow Pod for changes to apply. +==== + +`01-configmap_basic-props.yaml`:: +Holds application properties from application.properties. +Any change to this ConfigMap triggers an automatic Pod restart. + +`02-configmap_01-basic-resources-schemas.yaml`:: +Contains JSON schemas from src/main/resources/schemas. ++ +[NOTE] +==== +You do not need to deploy certain configuration resources when using the GitOps profile. +==== + +`03-sonataflow_basic.yaml`:: +The SonataFlow custom resource (CR) that defines the workflow. ++ +[source,yaml] +---- +podTemplate: + container: + image: quay.io/orchestrator/demo-basic + resources: {} + envFrom: + - secretRef: + name: basic-secrets +---- ++ +[source,yaml,subs="+quotes"] +---- +persistence: + postgresql: + secretRef: + name: `sonataflow-psql-postgresql` + userKey: `____` + passwordKey: `____` + serviceRef: + name: `sonataflow-psql-postgresql` + port: 5432 + databaseName: sonataflow + databaseSchema: basic +---- ++ +where: + +`postgresql:secretRef:name`:: Enter the Secret name for your deployment. +`postgresql:secretRef:userKey`:: Enter the key for your deployment. +`postgresql:secretRef:passwordKey`:: Enter the password for your deployment. +`postgresql:serviceRef:name`:: Enter the Service name for your deployment. ++ +If you must connect to an external database, replace `serviceRef` with `jdbcUrl`. See link:https://docs.redhat.com/en/documentation/red_hat_openshift_serverless/1.36/html-single/serverless_logic/index#serverless-logic-managing-persistence[Managing workflow persistence]. + +By default, the script generates all the manifests without a namespace. You can specify a namespace to the script by using the `--namespace` flag if you know the target namespace in advance. Otherwise, you must provide the namespace when applying the manifests to the cluster. See link:https://docs.redhat.com/en/documentation/red_hat_openshift_serverless/1.36/html-single/serverless_logic/index#serverless-logic-configuring-workflow-services[Configuring workflow services]. \ No newline at end of file diff --git a/modules/orchestrator/con-orchestrator-plugin-components.adoc b/modules/orchestrator/con-orchestrator-plugin-components.adoc deleted file mode 100644 index 40f53f85f3..0000000000 --- a/modules/orchestrator/con-orchestrator-plugin-components.adoc +++ /dev/null @@ -1,18 +0,0 @@ -:_mod-docs-content-type: CONCEPT - -[id="con-orchestrator-plugin-components.adoc_{context}"] -= Orchestrator plugin components on {ocp-short} - -To run the Orchestrator plugin successfully on {ocp-short}, you must first install the following required components: - -** {product} ({product-very-short}) {product-custom-resource-type} -** OpenShift Serverless Logic Operator -** OpenShift Serverless Operator -*** Knative Serving -*** Knative Eventing -** (Optional) For managing the Orchestrator project, you need a preinstalled instance of Argo CD or {company-name} OpenShift GitOps in the cluster. It is disabled by default. -** (Optional) To use Tekton tasks and the build pipeline, you need a preinstalled instance of Tekton or {company-name} OpenShift Pipelines in the cluster. These features are disabled by default. - -The most recommended approach to install the dependencies for the Orchestrator plugin is by enabling the dependencies for the Orchestrator plugin directly during your {product-very-short} installation. When you configure {product-very-short} to include the Orchestrator plugin, the {product-very-short} Operator installs the necessary OpenShift Serverless Operators, eliminating the need for separate scripts or Helm charts. - -For specific use cases, you can choose to install the dependencies manually or use helper utilities. diff --git a/modules/orchestrator/con-project-structure-overview.adoc b/modules/orchestrator/con-project-structure-overview.adoc new file mode 100644 index 0000000000..fb83bbf427 --- /dev/null +++ b/modules/orchestrator/con-project-structure-overview.adoc @@ -0,0 +1,32 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-project-structure-overview.adoc_{context}"] += Project structure overview + +The project utilizes *Quarkus project layout* (Maven project structure). This structure is illustrated by the following `01_basic` workflow example: + +[source, yaml] +---- +01_basic +├── pom.xml +├── README.md +└── src + └── main + ├── docker + │ ├── Dockerfile.jvm + │ ├── Dockerfile.legacy-jar + │ ├── Dockerfile.native + │ └── Dockerfile.native-micro + └── resources + ├── application.properties + ├── basic.svg + ├── basic.sw.yaml + ├── schemas + │ ├── basic__main-schema.json + │ └── workflow-output-schema.json + └── secret.properties +---- + +The main workflow resources are located under the `src/main/resources/` directory. + +The `kn-workflow CLI` generated this project structure. You can try generating the structure yourself by following the _Getting Started guide_. For more information on the Quarkus project, see link:https://quarkus.io/guides/getting-started[Creating your first application]. \ No newline at end of file diff --git a/modules/orchestrator/con-required-tools.adoc b/modules/orchestrator/con-required-tools.adoc new file mode 100644 index 0000000000..4c1081b31b --- /dev/null +++ b/modules/orchestrator/con-required-tools.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-required-tools.adoc_{context}"] += Required tools + +To run the `build-sh` script locally and manage the workflow lifecycle, you must install the following command-line tools: + +[cols="1,3", options="header"] +|=== +|Tool |Conceptual Purpose. +|podman or docker |Container runtime required for building the workflow images. +|`kubectl` |Kubernetes CLI. +|`yq` |YAML processor. +|`jq` |JSON processor. +|`curl`, `git`, `find`, `which`| Shell utilities. +|`kn-workflow` |CLI for generating workflow manifests. +|=== \ No newline at end of file diff --git a/modules/orchestrator/con-supported-architecture-for-orchestrator.adoc b/modules/orchestrator/con-supported-architecture-for-orchestrator.adoc deleted file mode 100644 index c5eca5b2ca..0000000000 --- a/modules/orchestrator/con-supported-architecture-for-orchestrator.adoc +++ /dev/null @@ -1,15 +0,0 @@ -:_mod-docs-content-type: CONCEPT - -[id="con-supported-architecture-for-orchestrator_{context}"] -= Supported architecture for Orchestrator - -You can use Orchestrator to design, run, and monitor workflows that automate key tasks. It builds on components like SonataFlow and OpenShift Serverless, which provide the runtime environment and event-driven capabilities needed to power your workflows. - -To help you get started quickly, the following Orchestrator plugin components are included but disabled by default in the `dynamic-plugins.default.yaml` file: - -* `"backstage-plugin-orchestrator"` -* `"backstage-plugin-orchestrator-backend-dynamic"` -* `"backstage-plugin-scaffolder-backend-module-orchestrator-dynamic"` -* `"backstage-plugin-orchestrator-form-widgets"` - -To enable these plugins, set the `plugins.disabled` parameter to `false`. diff --git a/modules/orchestrator/proc-building-locally.adoc b/modules/orchestrator/proc-building-locally.adoc new file mode 100644 index 0000000000..4ac66621d1 --- /dev/null +++ b/modules/orchestrator/proc-building-locally.adoc @@ -0,0 +1,35 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-building-locally.adoc_{context}"] += Building workflow images locally + +You can use the build script (`build.sh`) to build workflow images. You can run it either locally or inside a container. This section highlights how build workflow images locally. + +.Procedure + +. Clone the project as shown in the following example: ++ +[source, yaml] +---- +git clone git@github.com:rhdhorchestrator/orchestrator-demo.git +cd orchestrator-demo +---- + +. Check the help menu of the script: ++ +[source,yaml] +---- +./scripts/build.sh --help +---- + +. Run the `build.sh` script, providing the required flags, for instance, the image path (`-i`), workflow source directory (`-w`), and manifests output directory (`-m`). + ++ +[IMPORTANT] +==== +You must specify the full target image path with a tag as shown in the following example: +[source,yaml] +---- +./scripts/build.sh --image=quay.io/orchestrator/demo-basic:test -w 01_basic/ -m 01_basic/manifests +---- +==== \ No newline at end of file diff --git a/modules/orchestrator/proc-building-the-01-basic-workflow.adoc b/modules/orchestrator/proc-building-the-01-basic-workflow.adoc new file mode 100644 index 0000000000..6dad50f109 --- /dev/null +++ b/modules/orchestrator/proc-building-the-01-basic-workflow.adoc @@ -0,0 +1,27 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-building-the-01-basic-workflow.adoc_{context}"] += Building the `01_basic` workflow + +To run the script from the root directory of the repository, you must use the `-w` flag to point to the workflow directory. Additionally, specify the output directory with the `-m` flag. + +.Prerequisites + +* You have specified the target image using a tag. + +.Procedure + +. Run the following command: ++ +[source,bash] +---- +./scripts/build.sh --image=quay.io/orchestrator/demo-basic:test -w 01_basic/ -m 01_basic/manifests +---- ++ +This build command produces the following two artifacts: + +* A workflow image and Kubernetes manifests: `quay.io/orchestrator/demo-basic:test` and tagged as `latest`. +* Kubernetes manifests under: `01_basic/manifests/` + +. Optional: You can add the `--push` flag to automatically push the image after building. Otherwise, pushing manually is mandatory before deploying. + diff --git a/modules/orchestrator/proc-creating-and-running-workflows.adoc b/modules/orchestrator/proc-creating-and-running-workflows.adoc new file mode 100644 index 0000000000..f470822d8c --- /dev/null +++ b/modules/orchestrator/proc-creating-and-running-workflows.adoc @@ -0,0 +1,43 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-creating-and-running-workflows.adoc_{context}"] += Creating and running your serverless workflow project locally + +The `kn-workflow` CLI is an essential tool that generates workflow manifests and project structures. To ensure successful development and immediate testing, begin developing a new serverless workflow locally by completing the following steps: + +.Procedure +. Use the `kn-workflow` CLI to create a new workflow project, which adheres to the Quarkus structure as shown in the following example: ++ +[source,bash] +---- +kn-workflow quarkus create --name +---- + +. Edit the workflow, add schema and specific files, and run it locally from project folder as shown in the following example: ++ +[source,bash] +---- +kn-workflow quarkus run +---- +. Run the workflow locally using the `kn-workflow run` which pulls the following image: ++ +[source,yaml] +---- +registry.redhat.io/openshift-serverless-1/logic-swf-devmode-rhel8:1.36.0 +---- + +. For building the workflow image, the `kn-workflow` CLI pulls the following images: ++ +[source,yaml] +---- +registry.redhat.io/openshift-serverless-1/logic-swf-builder-rhel8:1.36.0-8 +registry.access.redhat.com/ubi9/openjdk-17:1.21-2 +---- + +[role="_additional-resources"] +.Additional resources + +* link:https://openshift-knative.github.io/docs/docs/latest/serverless-logic/about.html[About OpenShift Serverless Logic] +* link:https://redhat-scholars.github.io/serverless-workflow/osl/index.html[OpenShift Serverless Logic Tutorial] +* {configuring-book-link}#running-behind-a-proxy[Running {product} behind a corporate proxy] +* link:https://docs.redhat.com/en/documentation/red_hat_build_of_quarkus/3.15/html-single/getting_started_with_red_hat_build_of_quarkus/index#proc_online-maven_quarkus-getting-started[Using the Red Hat-hosted Quarkus repository] \ No newline at end of file diff --git a/modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc b/modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc new file mode 100644 index 0000000000..29cbcf7b11 --- /dev/null +++ b/modules/orchestrator/proc-deploying-workflows-on-a-cluster.adoc @@ -0,0 +1,108 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-deploying-workflows-on-a-cluster.adoc_{context}"] += Deploying workflows on a cluster + +You can deploy the workflow on a cluster, since the image is pushed to the image registry and the deployment manifests are available. + +.Prerequisites + +* You have an {ocp-short} cluster with the following versions of components installed: + +** {product} ({product-very-short}) `v1.7` +** Orchestrator plugins `v1.7.1` +** OpenShift Serverless `v1.36` +** OpenShift Serverless Logic `v1.36` ++ +For instructions on how to install these components, see the {orchestrator-book-link}#con-orchestrator-plugin-components.adoc_orchestrator-rhdh[Orchestrator plugin components on {ocp-short}]. + +* You must apply the workflow manifests in a namespace that contains a `SonataflowPlatform` custom resource (CR), which manages the link:https://docs.redhat.com/en/documentation/red_hat_openshift_serverless/1.36/html-single/serverless_logic/index#serverless-logic-configuring-workflow-services[supporting services]. + +.Procedure + +. Use the `kubectl create` command specifying the target namespace to apply the Kubernetes manifests as shown in the following example: ++ +[source,bash] +---- +kubectl create -n -f ./01_basic/manifests/. +---- + +. After deployment, monitor the status of the workflow pods as shown in the following example: ++ +[source,yaml] +---- +kubectl get pods -n -l app=basic +---- ++ +The pod may initially appear in an `Error` state because of missing or incomplete configuration in the Secret or ConfigMap. + +. Inspect the Pod logs as shown in the following example: ++ +[source,yaml] +---- +oc logs -n basic-f7c6ff455-vwl56 +---- ++ +The following code is an example of the output: ++ +[source,yaml] +---- +SRCFG00040: The config property quarkus.openapi-generator.notifications.auth.BearerToken.bearer-token is defined as the empty String ("") which the following Converter considered to be null: io.smallrye.config.Converters$BuiltInConverter +java.lang.RuntimeException: Failed to start quarkus +... +Caused by: io.quarkus.runtime.configuration.ConfigurationException: Failed to read configuration properties +---- ++ +The error indicates a missing property: `quarkus.openapi-generator.notifications.auth.BearerToken.bearer-token`. + +. In such a case where the logs show the `ConfigurationException: Failed to read configuration properties` error or indicate a missing value, retrieve the ConfigMap as shown in the following example: ++ +[source,yaml] +---- +oc get -n configmaps basic-props -o yaml +---- ++ +The following code is an example of the sample output: ++ +[source,yaml] +---- +apiVersion: v1 +data: + application.properties: | + # Backstage notifications service + quarkus.rest-client.notifications.url=${BACKSTAGE_NOTIFICATIONS_URL} + quarkus.openapi-generator.notifications.auth.BearerToken.bearer-token=${NOTIFICATIONS_BEARER_TOKEN} +... +---- ++ +Resolve the placeholders using values provided using a Secret. + +. You must edit the corresponding Secret and provide appropriate base64-encoded values to resolve the placeholders in `application.properties` as shown in the following example: ++ +[source,yaml] +---- +kubectl edit secrets -n basic-secrets +---- +. Restart the workflow Pod for Secret changes to take effect in OpenShift Serverless Logic `v1.36`. + +.Verification + +. Verify the deployment status by checking the Pods again as shown in the following example: ++ +[source,yaml] +---- +oc get pods -n -l app=basic +---- ++ +The expected status for a successfully deployed workflow Pod is as shown in the following example: ++ +[source,yaml] +---- +NAME READY STATUS RESTARTS AGE +basic-f7c6ff455-grkxd 1/1 Running 0 47s +---- + +. Once the Pod is in the `Running` state, the workflow now appears in the Orchestrator plugin inside the {product}. + +.Next steps +* Inspect the provided build script to extract the actual steps and implement them in your preferred CI/CD tool, for example, GitHub Actions, GitLab CI, Jenkins, and Tekton. \ No newline at end of file diff --git a/modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc b/modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc new file mode 100644 index 0000000000..7fce154dcb --- /dev/null +++ b/modules/orchestrator/proc-enabling-orchestrator-plugins-components.adoc @@ -0,0 +1,89 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-enabling-orchestrator-plugins-components.adoc_{context}"] += Enabling Orchestrator plugins components + +To use the Orchestrator, enable the Orchestrator plugins for {product}, that are disabled by default: + +Orchestrator frontend plugins:: + +`backstage-plugin-orchestrator`::: +Provides the interface for users to run and monitor workflows within {product-very-short}. You can run and track the execution status of processes. + +`backstage-plugin-orchestrator-form-widgets`::: +Provides custom widgets for the workflow execution form, allowing you to customize input fields and streamline the process of launching workflows. + +`backstage-plugin-orchestrator-form`::: +Provides the workflow execution form where you can define and submit the necessary input data required to start a new workflow instance. + +`backstage-plugin-orchestrator-form-api`::: +Defines the API for extending the workflow execution form. + +Orchestrator backend plugins:: + +`backstage-plugin-orchestrator-backend`::: +Gets workflow data into {product-short} making sure {product-very-short} ingests critical workflow metadata and runtime status fulfilling your need for visibility. + +`backstage-plugin-orchestrator-common`::: +Contains the backend OpenAPI specification along with autogenerated API documentation and client libraries. + +`scaffolder-backend-module-orchestrator`::: +Provides callable actions from scaffolder templates, such as `orchestrator:workflow:run` or `orchestrator:workflow:get_params`. + +Notification plugins:: + +`backstage-plugin-notifications`::: +Provides notification frontend components that allow you to display immediate, visible alerts about key workflow state changes, allowing real-time status tracking. + + +`backstage-plugin-signals`::: +Provides notification frontend components user experience enhancements so you can process the real-time lifecycle events. + +`backstage-plugin-notifications-backend-dynamic`::: +Provides notification backend components allowing you to manage and store the stream of workflow events, making sure that critical notifications are ready to be served to the front-end user interface. + +`backstage-plugin-signals-backend-dynamic`::: +Provides the backend components for notification user experience enhancements allowing you to establish the necessary communication channels for the event-driven orchestration that is core to Serverless Workflows. + +.Prerequisites + +* When using the {product} Helm chart, you have installed the necessary OpenShift Serverless Operators. ++ +[NOTE] +==== +When using the {product} Operator, the Operator installs the necessary OpenShift Serverless Operators automatically. For specific use cases, install the dependencies manually or use helper utilities. +==== + +* (Optional) For managing the Orchestrator project, you have an instance of Argo CD or Red Hat OpenShift GitOps in the cluster. It is disabled by default. + +* (Optional) To use Tekton tasks and the build pipeline, you have an instance of Tekton or Red Hat OpenShift Pipelines in the cluster. These features are disabled by default. + +.Procedure +* Locate your {product-short} configuration and enable the Orchestrator plugins and the supporting notification plugins. ++ +[source,yaml,subs="+attributes,+quotes"] +---- +plugins: + - package: "@redhat/backstage-plugin-orchestrator@{product-chart-version}" + disabled: false + - package: "@redhat/backstage-plugin-orchestrator-backend-dynamic@{product-chart-version}" + disabled: false + - package: "@redhat/backstage-plugin-scaffolder-backend-module-orchestrator-dynamic@{product-chart-version}" + disabled: false + - package: "@redhat/backstage-plugin-orchestrator-form-widgets@{product-chart-version}" + disabled: false + - package: "@redhat/backstage-plugin-orchestrator-common@{product-chart-version}" + disabled: false + - package: "@redhat/backstage-plugin-orchestrator-form@{product-chart-version}" + disabled: false + - package: "@redhat/backstage-plugin-orchestrator-form-api@{product-chart-version}" + disabled: false + - package: "./dynamic-plugins/dist/backstage-plugin-notifications" + disabled: false + - package: "./dynamic-plugins/dist/backstage-plugin-signals" + disabled: false + - package: "./dynamic-plugins/dist/backstage-plugin-notifications-backend-dynamic" + disabled: false + - package: "./dynamic-plugins/dist/backstage-plugin-signals-backend-dynamic" + disabled: false +---- \ No newline at end of file diff --git a/modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc b/modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc new file mode 100644 index 0000000000..cb008b876c --- /dev/null +++ b/modules/orchestrator/ref-compatibility-guide-for-orchestrator.adoc @@ -0,0 +1,19 @@ +:_mod-docs-content-type: REFERENCE + +[id="con-compatibility-guide-for-orchestrator.adoc_{context}"] += Compatibility guide for Orchestrator + +The following table lists the {product-very-short} Orchestrator plugin versions and their compatible corresponding infrastructure versions. + +[cols="2,2,2,2,2"] +|=== +| Orchestrator plugin version | {product} ({product-very-short}) version | OpenShift version | OpenShift Serverless Logic (OSL) version | OpenShift Serverless version +| Orchestrator `1.5` | `1.5` | `4.14` - `4.18` | OSL `1.35` | `1.35` +| Orchestrator `1.6` | `1.6` | `4.14` - `4.18` | OSL `1.36` | `1.36` +| Orchestrator `1.7` ({product-very-short} {product-version}) | {product-version} | `4.16` - `4.19` | OSL `1.36` | `1.36` +|=== + +[NOTE] +==== +Orchestrator plugin supports the same {ocp-short} versions as {product-very-short}. See the link:https://access.redhat.com/support/policy/updates/developerhub?extIdCarryOver=true&sc_cid=RHCTG0180000371695[Life Cycle] page. +==== \ No newline at end of file diff --git a/modules/software-catalogs/proc-registering-components-manually-in-the-rhdh-instance.adoc b/modules/software-catalogs/proc-registering-components-manually-in-the-rhdh-instance.adoc index 110d8056a0..da00660c6e 100644 --- a/modules/software-catalogs/proc-registering-components-manually-in-the-rhdh-instance.adoc +++ b/modules/software-catalogs/proc-registering-components-manually-in-the-rhdh-instance.adoc @@ -14,7 +14,6 @@ To manually register components in your {product-very-short} instance, create a . In the root directory of your software project, create a file named `catalog-info.yaml`. + -.Example of a `catalog-info.yaml` file [source,yaml] ---- apiVersion: backstage.io/v1alpha1 diff --git a/modules/software-catalogs/proc-starring-components-in-the-software-catalog.adoc b/modules/software-catalogs/proc-starring-components-in-the-software-catalog.adoc index 01a1ed3050..b09d242145 100644 --- a/modules/software-catalogs/proc-starring-components-in-the-software-catalog.adoc +++ b/modules/software-catalogs/proc-starring-components-in-the-software-catalog.adoc @@ -11,7 +11,7 @@ You can use the *Add to favorites* icon to add the software catalogs that you vi To quickly access the Software Catalogs that you visit regularly, complete the following steps: . In your {product} navigation menu, click *Catalog*. -. Find the software component that you want to add as a favorite, then click the *Add to favorites* icon under *Actions*. +. Find the software component that you want to add as a favorite, under *Actions*, click the *Add to favorites* icon. .Verification diff --git a/modules/software-catalogs/proc-updating-components-in-the-software-catalog.adoc b/modules/software-catalogs/proc-updating-components-in-the-software-catalog.adoc index 5f460b1903..03e219c0a6 100644 --- a/modules/software-catalogs/proc-updating-components-in-the-software-catalog.adoc +++ b/modules/software-catalogs/proc-updating-components-in-the-software-catalog.adoc @@ -15,7 +15,7 @@ You can update components in the Software Catalog in your {product} instance. To update components in the Software Catalog in your {product} instance, complete the following steps: . In your {product} navigation menu, click *Catalog*. -. Find the software component that you want to edit, then click the *Edit* icon under *Actions*. +. Find the software component that you want to edit, under *Actions*, click the *Edit* icon. + [NOTE] diff --git a/modules/software-catalogs/proc-viewing-software-catalog-yaml.adoc b/modules/software-catalogs/proc-viewing-software-catalog-yaml.adoc index 607cae63d3..1e2fac516e 100644 --- a/modules/software-catalogs/proc-viewing-software-catalog-yaml.adoc +++ b/modules/software-catalogs/proc-viewing-software-catalog-yaml.adoc @@ -10,7 +10,7 @@ You can view the Software Catalog YAML file in your {product} instance. The YAML To view the Software Catalog YAML file in your {product} instance, complete the following steps: . In your {product} navigation menu, click *Catalog*. -. Find the software component that you want to view, then click the *View* icon under *Actions*. +. Find the software component that you want to view, under *Actions*, click the *View* icon. + [NOTE] diff --git a/titles/configuring/master.adoc b/titles/configuring/master.adoc index bdf974fbb2..e3dc73ec39 100644 --- a/titles/configuring/master.adoc +++ b/titles/configuring/master.adoc @@ -11,12 +11,12 @@ include::artifacts/attributes.adoc[] :platform-cli-name: {ocp-brand-name} CLI ('oc') :a-platform-generic: an OpenShift :platform-generic: OpenShift +:optional-steps: enable [id="{context}"] = {title} {abstract} - include::assemblies/assembly-provisioning-a-custom-configuration.adoc[leveloffset=+1] @@ -35,7 +35,7 @@ include::assemblies/assembly-configuring-high-availability.adoc[leveloffset=+1] include::assemblies/assembly-configuring-a-proxy.adoc[leveloffset=+1] -include::modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc[leveloffset=+1] +include::modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc[leveloffset=+1] include::assemblies/dynamic-plugins/assembly-using-the-dynamic-plugins-cache.adoc[leveloffset=+1] diff --git a/titles/customizing/master.adoc b/titles/customizing/master.adoc index d5c480b50e..29898dda63 100644 --- a/titles/customizing/master.adoc +++ b/titles/customizing/master.adoc @@ -45,3 +45,5 @@ include::assemblies/assembly-customizing-the-homepage.adoc[leveloffset=+1] include::assemblies/assembly-customizing-the-quick-access-card.adoc[leveloffset=+1] include::modules/customizing/proc-customizing-rhdh-metadata-card.adoc[leveloffset=+1] + +include::assemblies/assembly-localization-in-rhdh.adoc[leveloffset=+1] diff --git a/titles/install-rhdh-air-gapped/master.adoc b/titles/install-rhdh-air-gapped/master.adoc index 104ac69897..0b0ed23cc0 100644 --- a/titles/install-rhdh-air-gapped/master.adoc +++ b/titles/install-rhdh-air-gapped/master.adoc @@ -6,6 +6,7 @@ include::artifacts/attributes.adoc[] = {title} :context: title-install-rhdh-air-grapped :imagesdir: images +:optional-steps: disable include::modules/installation/con-airgapped-environment.adoc[leveloffset=+1] diff --git a/titles/install-rhdh-aks/master.adoc b/titles/install-rhdh-aks/master.adoc index 0e164dbf98..b631552ff2 100644 --- a/titles/install-rhdh-aks/master.adoc +++ b/titles/install-rhdh-aks/master.adoc @@ -14,6 +14,7 @@ include::artifacts/attributes.adoc[] [id="{context}"] = {title} :imagesdir: images +:optional-steps: disable {abstract} diff --git a/titles/install-rhdh-eks/master.adoc b/titles/install-rhdh-eks/master.adoc index b3eeb48d78..48b9e529be 100644 --- a/titles/install-rhdh-eks/master.adoc +++ b/titles/install-rhdh-eks/master.adoc @@ -14,6 +14,7 @@ include::artifacts/attributes.adoc[] [id="{context}"] = {title} :imagesdir: images +:optional-steps: disable {abstract} diff --git a/titles/install-rhdh-gke/master.adoc b/titles/install-rhdh-gke/master.adoc index e6c4652d04..e6153e64ba 100644 --- a/titles/install-rhdh-gke/master.adoc +++ b/titles/install-rhdh-gke/master.adoc @@ -14,6 +14,7 @@ include::artifacts/attributes.adoc[] [id="{context}"] = {title} :imagesdir: images +:optional-steps: disable {abstract} diff --git a/titles/orchestrator/master.adoc b/titles/orchestrator/master.adoc index 97584be038..f483c3021e 100644 --- a/titles/orchestrator/master.adoc +++ b/titles/orchestrator/master.adoc @@ -8,4 +8,6 @@ include::artifacts/attributes.adoc[] include::assemblies/assembly-orchestrator-rhdh.adoc[leveloffset=+1] -include::assemblies/assembly-install-rhdh-orchestrator.adoc[leveloffset=+1] \ No newline at end of file +include::assemblies/assembly-building-and-deploying-serverless-workflows.adoc[leveloffset=+1] + +include::assemblies/assembly-install-rhdh-orchestrator.adoc[leveloffset=+1] diff --git a/titles/plugins-rhdh-install/master.adoc b/titles/plugins-rhdh-install/master.adoc index fff65e1cf0..427a161ca8 100644 --- a/titles/plugins-rhdh-install/master.adoc +++ b/titles/plugins-rhdh-install/master.adoc @@ -11,6 +11,9 @@ include::artifacts/attributes.adoc[] //installing dynamic plugins include::assemblies/dynamic-plugins/assembly-installing-rhdh-plugins.adoc[leveloffset=+1] +// Converting a custom plugin to a dynamic plugin +include::assemblies/dynamic-plugins/assembly-converting-custom-plugin-to-dynamic-plugin.adoc[leveloffset=+1] + //third-party plugins include::assemblies/dynamic-plugins/assembly-third-party-plugins.adoc[leveloffset=+1] diff --git a/titles/setting-up-and-configuring-your-first-red-hat-developer-hub-instance/master.adoc b/titles/setting-up-and-configuring-your-first-red-hat-developer-hub-instance/master.adoc index c0c66a8943..f2f3875d2e 100644 --- a/titles/setting-up-and-configuring-your-first-red-hat-developer-hub-instance/master.adoc +++ b/titles/setting-up-and-configuring-your-first-red-hat-developer-hub-instance/master.adoc @@ -3,8 +3,31 @@ include::artifacts/attributes.adoc[] :subtitle: Prepare your IT infrastructure including {ocp-brand-name} and required external components, and run your first {product} ({product-very-short}) instance in production. :abstract: Prepare your IT infrastructure including {ocp-brand-name} and required external components, and run your first {product} ({product-very-short}) instance in production. :context: setting-up-and-configuring-your-first-rhdh-instance +:optional-steps: disable [id="{context}"] = {title} {abstract} +include::modules/configuring/con-checklist-to-run-your-first-rhdh-instance-in-production.adoc[leveloffset=+1] + +include::modules/installation/proc-install-operator.adoc[leveloffset=+1] + +include::modules/configuring/proc-preparing-your-external-services.adoc[leveloffset=+1] + +include::modules/configuring/proc-provisioning-your-custom-configuration.adoc[leveloffset=+1] + +// TODO: Understanding the software catalog + +include::assemblies/assembly-enabling-authentication-with-mandatory-steps-only.adoc[leveloffset=+1] + + +include::modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration-in-getting-started-context.adoc[leveloffset=+1] + +include::modules/customizing-the-appearance/proc-customize-rhdh-theme-mode.adoc[leveloffset=+1] + +include::assemblies/assembly-managing-authorizations-by-using-the-rhdh-web-ui.adoc[leveloffset=+1] + +// TODO: Importing manually a Git repository +// TODO: Running a CI pipeline: GitHub; CF + Tekton +// TODO: Configuring Software Templates