Procedure

1. Make sure the required plugins are enabled in your RHDH my-rhdh-app-config file or the Backstage custom resource (CR):

   global:
     dynamic:
       plugins:
         - package: ./dynamic-plugins/dist/backstage-community-plugin-catalog-backend-module-scaffolder-relation-processor-dynamic
           disabled: false
         - package: ./dynamic-plugins/dist/backstage-plugin-notifications
           disabled: false
         - package: ./dynamic-plugins/dist/backstage-plugin-notifications-backend-dynamic
           disabled: false

2. Modify the Software Template that you want to update.
3. Complete one or both of the following tasks:
4. Include the annotation in your template: Add the backstage.io/template-version annotation in your template metadata. When this annotation is present, it is automatically used to annotate your catalog entity and display a default version value.

5. Pass the annotation as input to the action: This method takes precedence over the annotation in the template itself and allows the user running the template to specify the version.

   # ...
   - id: version-templateRef
     name: Append the version of this template to the entityRef
     action: catalog:template:version
     input:
       annotations:
         backstage.io/template-version: ${{ parameters.version }}
   # ...

Verification

1. Create a catalog component using the updated Software Template. This step creates a new component in Backstage and optionally, pushes files to an external repository (for example, GitHub, GitLab).

2. Check the component in the Catalog UI.

   1. On the Catalog page, locate the newly created catalog component.
   2. Verify that the backstage.io/template-version annotation is present in the entity. You can use INSPECT ENTITY and select YAML Raw or JSON Raw view to find the annotation in the component definition.

3. Only if you have published the catalog component: Check the component file in the repository.

   1. If VIEW SOURCE is present in your UI: Click VIEW SOURCE to open the stored component file in the repository.
   2. Locate the file manually and verify that the backstage.io/template-version annotation is present.

Procedure

1. Open your RHDH app-config.yaml file.
2. Add the following configuration to the scaffolder section to enable Software Template update notifications

3. Optional: To customize the notification title and description, add the message block:

   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

   The message:title and message:description fields support the $ENTITY_DISPLAY_NAME variable. The system replaces this variable with the title (or the name, if the title is missing) of the scaffolded entity.

Verification

1. Log in to your Red Hat Developer Hub instance.
2. In the left navigation menu, verify that the Notifications item is displayed.
3. Update the version of a Software Template and verify that the owner of a component scaffolded from that template receives a notification.

Procedure

1. Locate the Software Template object YAML file where you want to add the provenance information and add a step that uses the catalog:scaffolded-from action. This action links the resulting catalog entity back to the source template.

2. Optional: To track the template version (for example, v1.0 versus v1.5), include the catalog:template:version action in the steps section. The following code block is an example to adding versioning action to the steps section:

   steps:
     - id: create-provenance-annotation
       name: Append the entityRef of this template to the entityRef
       action: catalog:scaffolded-from
     - id: create-version-annotation
       name: Create Template Version Annotation
       action: catalog:template:version
       input:
         templateVersion: ${{ parameters.version }}
     - ... other steps ...

   where:

   steps:input:templateVersion

   Reads the version parameter

   Note

   The catalog:template:version action reads a version parameter defined in the template and applies it as an annotation to the resulting catalog entity.

3. In your Red Hat Developer Hub app-config.yaml file, configure the catalog.locations section to point to the Software Template that you want to add. You might need to add Template to the global catalog.rules.allow list or add a granular rule to the location to allow for Software Templates ingestion, as shown in the following example:

   # ...
   catalog:
     locations:
       - type: url
         target: https://<repository_url>/example-template.yaml
         rules:
           - allow: [Template]
   # ...

   where:

   catalog.locations.type

   Enter the url type if you are importing templates from a repository, such as GitHub or GitLab.

   catalog.locations.target

   Enter the URL for the template.

   catalog.locations.rules.allow

   Enter the Template rule to allow new Software Templates to be added to the catalog.

1. In the Red Hat Developer Hub navigation menu, go to Catalog and locate the newly created catalog component.
2. To view the underlying data that links the entity to the template, select the INSPECT ENTITY option.

3. To verify provenance annotations, complete the following steps:

   1. Select the YAML Raw or JSON Raw view and verify the presence of the data item for the scaffoldedFrom link.

   2. Optional: If versioning was included, verify the presence of the backstage.io/template-version annotation.

      Note

      If you publish the catalog component to an external repository (such as Git), the component file in that repository must also contain the backstage.io/template-version annotation.

Procedure

1. In the Red Hat Developer Hub navigation menu, click Catalog, use the filters to find and select the Software Template you want to inspect.
2. In the Software Template detail page, click the Dependencies tab. This view lists all catalog entities such as components, resources, and systems that reference this template, including any version information if configured.

Procedure

1. Enable the template sync and notification plugins in your RHDH dynamic-plugins.yaml file:

   plugins:
   # Enables the core template synchronization logic
     - package: './dynamic-plugins/dist/backstage-community-plugin-scaffolder-backend-module-scaffolder-relation-processor'
       disabled: false
   # Required only if you want to receive notifications for new pull requests
     - package: './dynamic-plugins/dist/backstage-plugin-notifications'
       disabled: false

2. Open your RHDH app-config.yaml file.

3. Configure the pull request (PR) feature by adding the following configuration:

   scaffolder:
     pullRequests:
       templateUpdate:
         enabled: true

4. Optional: Enable notifications to alert entity owners when a PR is created:

   scaffolder:
     notifications:
       templateUpdate:
         enabled: true

5. Restart the Red Hat Developer Hub instance to apply the changes.

Verification

1. Update the version of a source template in its repository.
2. Navigate to a repository scaffolded from that template.
3. Confirm that a new pull request named [component-name]/template-upgrade-v[version] exists.

Procedure

1. Navigate to the Create page in the RHDH interface.
2. Select Register Component.
3. Enter the full URL to your template.yaml file in the Repository URL field.
4. Click Analyze and then Import.

Verification

1. Navigate to the Create page.
2. Confirm that your new template is displayed in the list of available options.

Procedure

1. For security, store your secrets as environment variables values in an OpenShift Container Platform secret, rather than in plain text in your configuration files. Collect all your secrets in the secrets.txt file, with one secret per line in KEY=value form.

   Enter your authentication secrets.

2. Author your custom app-config.yaml file. This is the main Developer Hub configuration file. You need a custom app-config.yaml file to avoid the Developer Hub installer to revert user edits during upgrades. When your custom app-config.yaml file is empty, Developer Hub is using default values.

   • To prepare a deployment with the Red Hat Developer Hub Operator on OpenShift Container Platform, you can start with an empty file.

   • To prepare a deployment with the Red Hat Developer Hub Helm chart, or on Kubernetes, enter the Developer Hub base URL in the relevant fields in your app-config.yaml file to ensure proper functionality of Developer Hub. The base URL is what a Developer Hub user sees in their browser when accessing Developer Hub. The relevant fields are baseUrl in the app and backend sections, and origin in the backend.cors subsection:

     Configuring the baseUrl in app-config.yaml:

     app:
       title: Red Hat Developer Hub
       baseUrl: https://<my_developer_hub_domain>
     
     backend:
       auth:
         externalAccess:
           - type: legacy
             options:
               subject: legacy-default-config
               secret: "${BACKEND_SECRET}"
       baseUrl: https://<my_developer_hub_domain>
       cors:
         origin: https://<my_developer_hub_domain>

   • Optionally, enter your configuration such as:

     • Authentication in Red Hat Developer Hub.
     • Authorization in Red Hat Developer Hub.
     • Customization.
     • Configure your OpenShift Container Platform integration.

3. Author your custom dynamic-plugins.yaml file to enable plugins. By default, Developer Hub 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.

   Enable the GitHub repository discovery and the RBAC features:

   dynamic.plugins.yaml

   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

4. Provision your custom configuration files to your OpenShift Container Platform cluster.

   1. Create the <my-rhdh-project> project aimed at containing your Developer Hub instance.

      $ oc create namespace my-rhdh-project

   2. Create config maps for your app-config.yaml and dynamic-plugins.yaml files in the <my-rhdh-project> project.

      $ oc create configmap my-rhdh-app-config --from-file=app-config.yaml --namespace=my-rhdh-project
      $ oc create configmap dynamic-plugins-rhdh --from-file=dynamic-plugins.yaml --namespace=my-rhdh-project

      You can also create the config maps by using the web console.

   3. Provision your secrets.txt file to the my-rhdh-secrets secret in the <my-rhdh-project> project.

      $ oc create secret generic my-rhdh-secrets --from-file=secrets.txt --namespace=my-rhdh-project

      You can also create the secret by using the web console.

Procedure

1. Author your Backstage CR in a my-rhdh-custom-resource.yaml file to use your custom config maps and secrets.

   Minimal my-rhdh-custom-resource.yaml custom resource example:

   apiVersion: rhdh.redhat.com/v1alpha5
   kind: Backstage
   metadata:
     name: my-rhdh-custom-resource
   spec:
     application:
       appConfig:
         mountPath: /opt/app-root/src
         configMaps:
            - name: my-rhdh-app-config
       extraEnvs:
         secrets:
            - name: <my_product_secrets>
       extraFiles:
         mountPath: /opt/app-root/src
       route:
         enabled: true
     database:
       enableLocalDb: true

   my-rhdh-custom-resource.yaml custom resource example with dynamic plugins and RBAC policies config maps, and external PostgreSQL database secrets:

   apiVersion: rhdh.redhat.com/v1alpha5
   kind: Backstage
   metadata:
     name: <my-rhdh-custom-resource>
   spec:
     application:
       appConfig:
         mountPath: /opt/app-root/src
         configMaps:
            - name: my-rhdh-app-config
            - name: rbac-policies
       dynamicPluginsConfigMapName: dynamic-plugins-rhdh
       extraEnvs:
         secrets:
            - name: <my_product_secrets>
            - name: my-rhdh-database-secrets
       extraFiles:
         mountPath: /opt/app-root/src
         secrets:
           - name: my-rhdh-database-certificates-secrets
             key: postgres-crt.pem, postgres-ca.pem, postgres-key.key
       route:
         enabled: true
     database:
       enableLocalDb: false

   Mandatory fields

   No fields are mandatory. You can create an empty Backstage CR and run Developer Hub with the default configuration.

   Optional fields

   spec.application.appConfig.configMaps

   Enter your config map name list.

   Mount files in the my-rhdh-app-config config map:

   spec:
     application:
       appConfig:
         mountPath: /opt/app-root/src
         configMaps:
            - name: my-rhdh-app-config

   Mount files in the my-rhdh-app-config and rbac-policies config maps:

   spec:
     application:
       appConfig:
         mountPath: /opt/app-root/src
         configMaps:
            - name: my-rhdh-app-config
            - name: rbac-policies

   spec.application.extraEnvs.envs

   Optionally, enter your additional environment variables that are not secrets, such as your proxy environment variables.

   Inject your HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables:

   spec:
     application:
       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'

   spec.application.extraEnvs.secrets

   Enter your environment variables secret name list.

   Inject the environment variables in your Red Hat Developer Hub secret:

   spec:
     application:
       extraEnvs:
         secrets:
            - name: <my_product_secrets>

   Inject the environment variables in the Red Hat Developer Hub and my-rhdh-database-secrets secrets:

   spec:
     application:
       extraEnvs:
         secrets:
            - name: <my_product_secrets>
            - name: my-rhdh-database-secrets

   Note

   <my_product_secrets> is your preferred Developer Hub secret name, specifying the identifier for your secret configuration within Developer Hub.

   spec.application.extraFiles.secrets

   Enter your certificates files secret name and files list.

   Mount the postgres-crt.pem, postgres-ca.pem, and postgres-key.key files contained in the my-rhdh-database-certificates-secrets secret:

   spec:
     application:
       extraFiles:
         mountPath: /opt/app-root/src
         secrets:
           - name: my-rhdh-database-certificates-secrets
             key: postgres-crt.pem, postgres-ca.pem, postgres-key.key

   spec.database.enableLocalDb

   Enable or disable the local PostgreSQL database.

   Disable the local PostgreSQL database generation to use an external postgreSQL database:

   spec:
     database:
       enableLocalDb: false

   On a development environment, use the local PostgreSQL database:

   spec:
     database:
       enableLocalDb: true

   spec.deployment

   Optionally, enter your deployment configuration.

2. Apply your Backstage CR to start or update your Developer Hub instance:

   $ oc apply --filename=my-rhdh-custom-resource.yaml --namespace=my-rhdh-project

Procedure

1. Configure Helm to use your custom configuration files in Developer Hub.

   1. Go to the Helm tab to see the list of Helm releases.
   2. Click the overflow menu on the Helm release that you want to use and select Upgrade.
   3. Use the YAML view to edit the Helm configuration.

   4. Set the value of the upstream.backstage.extraAppConfig.configMapRef and upstream.backstage.extraAppConfig.filename parameters as follows:

      upstream:
        backstage:
          extraAppConfig:
            - configMapRef: my-rhdh-app-config
              filename: app-config.yaml

   5. Click Upgrade.

Procedure

1. Perform one of the following steps based on your role:

2. As an administrator, set the proxy information in the Operator’s default ConfigMap file:

   1. Search for a ConfigMap file named backstage-default-config in the default namespace rhdh-operator and open it.
   2. Find the deployment.yaml key.

   3. Set the value of the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables in the Deployment spec as shown in the following example:

      # ...
        deployment.yaml: |-
          apiVersion: apps/v1
          kind: Deployment
          spec:
            template:
              spec:
                # ...
                initContainers:
                  - name: install-dynamic-plugins
                    # ...
                    env:
                      - name: NPM_CONFIG_USERCONFIG
                        value: /opt/app-root/src/.npmrc.dynamic-plugins
                      - 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'
                    # ...
                containers:
                  - name: backstage-backend
                    # ...
                    env:
                      - name: APP_CONFIG_backend_listen_port
                        value: "7007"
                      - 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'

3. As a developer, set the proxy information in your Backstage CR file as shown in the following example:

   spec:
     # ...
     application:
       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'

4. Save the configuration changes.

Procedure

1. Set the proxy information in your Helm configuration file:

   upstream:
     backstage:
       extraEnvVars:
         - name: HTTP_PROXY
           value: '<http_proxy_url>'
         - name: HTTPS_PROXY
           value: '<https_proxy_url>'
         - name: NO_PROXY
           value: '<no_proxy_settings>'

   Where,

   <http_proxy_url>

   Denotes a variable that you must replace with the HTTP proxy URL.

   <https_proxy_url>

   Denotes a variable that you must replace with the HTTPS proxy URL.

   <no_proxy_settings>

   Denotes a variable that you must replace with comma-separated URLs, which you want to exclude from proxying, for example, <example1>.com,<example2>.com.

   For example:

   upstream:
     backstage:
       extraEnvVars:
         - 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'

2. Save the configuration changes.

Procedure

1. Publish the JSON file containing your Learning Paths data to a web server, such as GitHub or GitLab. You can find an example at https://raw.githubusercontent.com/redhat-developer/rhdh/release-1.10/packages/app/public/learning-paths/data.json.

2. Configure the Developer Hub proxy to access the Learning Paths data from the hosted JSON file, by adding the following to the app-config.yaml file:

   proxy:
     endpoints:
       '/developer-hub':
         target: <target>
         pathRewrite:
           '^/api/proxy/developer-hub/learning-paths': '<learning_path.json>'
         changeOrigin: true
         secure: true

   <target>

   Enter the hosted JSON file base URL, such as https://raw.githubusercontent.com.

   <learning_path.json>

   Enter the hosted JSON file path without the base URL, such as '/redhat-developer/rhdh/main/packages/app/public/learning-paths/data.json'

   Tip

   When also configuring the home page, due to the use of overlapping pathRewrites for both the learning-path and homepage quick access proxies, create the learning-paths configuration (^api/proxy/developer-hub/learning-paths) before you create the homepage configuration (^/api/proxy/developer-hub). For example:

   proxy:
     endpoints:
       '/developer-hub':
         target: https://raw.githubusercontent.com/
         pathRewrite:
           '^/api/proxy/developer-hub/learning-paths': '/redhat-developer/rhdh/main/packages/app/public/learning-paths/data.json'
           '^/api/proxy/developer-hub': '/redhat-developer/rhdh/main/packages/app/public/homepage/data.json'
         changeOrigin: true
         secure: true

Procedure

1. Deploy your Developer Hub customization service on the same OpenShift Container Platform cluster as your Developer Hub instance. You can find an example at red-hat-developer-hub-customization-provider, that provides the same data as default Developer Hub data. The customization service provides a Learning Paths data URL such as: http://<rhdh-customization-provider>/learning-paths.

2. Configure the Developer Hub proxy to use your dedicated service to provide the Learning Path data, add the following to the app-config.yaml file:

   proxy:
     endpoints:
       '/developer-hub/learning-paths':
         target: <learning_path_data_url>
         changeOrigin: true
         qsecure: true # Change to "false" in case of using self hosted cluster with a self-signed certificate

Procedure

1. In your Red Hat Developer Hub navigation menu, click Learning Paths.

2. Select the tile for the course you want to begin.

   Note

   This action redirects you to the main page of the course in the Red Hat Developers site.

Procedure

1. Copy the default configuration and modify the field values to suit your needs. You can adjust the priority value of each header component to control its position. Additionally, you can enable or disable components by adding or removing them from the configuration. To ensure that the remaining header buttons align with the end of the header before the profile dropdown button, set config.props.growFactor to 1 in the Spacer mount point to enable the Spacer component. For example:

   - mountPoint: global.header/component
     importName: Spacer
     config:
       priority: 100
       props:
         growFactor: 1

2. To use your custom header, you must install it as a dynamic plugin by adding your plugin configuration to your app-config-dynamic.yaml file. For example:

   - package: <npm_or_oci_package_reference>
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           <package_name>:
             mountPoints:
               - mountPoint: application/header
                 importName: <application_header_name>
                 config:
                   position: above-main-content
               - mountPoint: global.header/component
                 importName: <header_component_name>
                 config:
                   priority: 100
               - mountPoint: global.header/component
                 importName: <header_component_name>
                 config:
                   priority: 90

   where:

   <npm_or_oci_package_reference>

   Specifies the package name.

   <application_header_name>

   Specifies the name of the application header. For example: MyHeader

   <header_component_name>

   Specifies the name of the header component. For example: MyHeaderComponent

   Note

   importName is an optional name referencing the value returned by the scaffolder field extension API.

3. Optional: To disable the global header, set the value of the disabled field to true in your dynamic-plugins.yaml file. For example:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header
     disabled: true

4. Optional: To display the Support button in the header, configure the app.support.url and app.support.items fields in your app-config.yaml file. For example:

   app:
     support:
       url: https://support.example.com
       items:
         - title: Support
           links:
             - url: https://support.example.com
               title: Open a support case

Procedure

1. To display a custom company logo in the global header, update the configuration with a mount point for CompanyLogo:

   # ...rest of the global header configuration
   red-hat-developer-hub.backstage-plugin-global-header:
     mountPoints:
       - mountPoint: application/header
         importName: GlobalHeader
         config:
           # Supported values: above-main-content | above-sidebar
           position: above-main-content
   
       - mountPoint: global.header/component
         importName: CompanyLogo
         config:
           priority: 200
           props:
             # Path to navigate when users click the logo:
             to: '/catalog'
             width: 300
             height: 200
             logo: <string> or <object> # Logo can be a base64 string or theme-specific object
               # Example 1: Single logo for all themes
               # logo: "<base64_encoded_images>"
   
               # Example 2: Theme-specific logos
               # logo:
                   dark: 'data:image/png;base64,...' # Used in dark theme
                   light: 'data:image/png;base64,...' # Used in light theme

2. (Optional) If you do not provide logo props to the CompanyLogo component, the component instead uses values defined under app.branding in your app-config.yaml file. You can configure the CompanyLogo as shown in the following configuration:

   app:
     branding:
       fullLogoWidth: 220  # Fallback width
       fullLogo: <string> or <object> #fullLogo can be a base64 string or theme-specific object
   
       # Example 1: Single logo for all themes
       #fullLogo: "<base64_encoded_image>
       # Example 2: Theme-specific logos
       #fullLogo:
           dark: 'data:image/png;base64,...' # Used in dark theme
           light: 'data:image/png;base64,...' # Used in light theme

   CompanyLogo uses the following configuration elements to control fallback and sizing behavior:

   • Logo source priority

     • The component selects the logo source in the following order:

       First, CompanyLogo props (logo, logo.light, logo.dark), then, app.branding.fullLogo. If you do not provide a logo through either, the component displays the default Developer Hub theme-specific logo.

   • Logo width priority

     • The component applies the first available value from props.width, then app.branding.fullLogoWidth from app-config.yaml. If you do not specify the width using either, the component applies a default width (150px).

       Note

       CompanyLogo preserves the images aspect ratio and never crops or distorts it. If the configured width results in a height greater than the maximum allowed (default: 40px), the image is automatically scaled down. As a result, adjusting only the width might not visibly change the logo unless the height is also configured.

       Increasing the logo height increases the height of the global header. The component first applies the value from props.height. If you do not specify the height, the component applies a default height (40px).

Verification

1. The logo is displayed correctly in the global header.
2. Click the logo to confirm it redirects to the path you defined in props.to.
3. Toggle between light and dark themes to ensure the correct logo loads in each.
4. (Optional) Temporarily remove the CompanyLogo props to test the fallback to app.branding.fullLogo.

Procedure

1. 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:

   app:
     sidebar:
       logo: true

   Note

   To display the logo in only the sidebar, remove the CompanyLogo component from the configuration.

2. To display the same logo in the sidebar for all themes, update the configuration as shown in the following configuration:

   app:
     sidebar:
       logo: true
     branding:
       fullLogoWidth: 220
       fullLogo: 'data:image/svg+xml;base64,...'

3. For theme-specific logos, you can configure the sidebar logo as shown in the following configuration:

   app:
     sidebar:
       logo: true
     branding:
       fullLogoWidth: 220
       fullLogo:
         light: 'data:image/svg+xml;base64,...'
         dark: 'data:image/svg+xml;base64,...'

Verification

1. The logo is displayed correctly in the sidebar.
2. Toggle between light and dark themes to ensure the correct logo loads in each.

Procedure

1. To configure spec.profile.displayName, use the following code:

   apiVersion: backstage.io/v1alpha1
   kind: User
   metadata:
     # Required unique username
     name: <my_display_name>
     # Optional preferred title
     title: <display_name_title>
   spec:
     profile:
       # Optional preferred display name (highest priority)
       displayName: <my_display_name>
     memberOf: [janus-authors]

2. To configure metadata.title rather than spec.profile.displayname, use the following code:

   apiVersion: backstage.io/v1alpha1
   kind: User
   metadata:
     # Required unique username
     name: <my_display_name>
     # Optional preferred title
     title: <display_name_title>
   spec:
     memberOf: [janus-authors]

3. To configure neither spec.profile.displayname or metadata.title, use the following code:

   apiVersion: backstage.io/v1alpha1
   kind: User
   metadata:
     # Required unique username
     name: <my_display_name>
   spec:
     memberOf: [janus-authors]

   Note

   The application falls back to metadata.name when you do not register the user entity.

Procedure

1. Locate your dynamic-plugin configuration.
2. Operator deployment: The configuration is stored in a ConfigMap referenced by your Backstage custom resource (CR).
3. Helm deployment: The configuration is in your values.yaml file or separate configuration files.
4. Enable the global header plugin. Ensure that the red-hat-developer-hub-backstage-plugin-global-header entry exists under the plugins: list and that disabled is set to false.

5. Verify that you enabled the global header plugin. Confirm that you listed the red-hat-developer-hub-backstage-plugin-global-header plugin under plugins: with disabled: false (or without a disabled property):

     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-header
       disabled: false

6. Add the required components. Under the mountPoints section of the plugin, add the components as shown in the following example:

     mountPoints:
       - mountPoint: application/header
         importName: GlobalHeader
         config:
           position: above-sidebar
       - mountPoint: global.header/component
         importName: StarredDropdown
         config:
           priority: 85
       - mountPoint: global.header/component
         importName: ApplicationLauncherDropdown
         config:
           priority: 82
       - mountPoint: global.header/component
         importName: MenuItemLink
         config:
           section: Documentation
         priority: 150
         props:
             title: Developer Hub
             icon: developerHub
             link: https://docs.redhat.com/en/documentation/red_hat_developer_hub
       - mountPoint: global.header/application-launcher
       importName: MenuItemLink
       config:
         section: Developer Tools
         priority: 100
         props:
             title: "RHDH Local"
             icon: developerHub
             link: https://github.com/redhat-developer/rhdh-local

7. Apply the configuration.
8. Operator deployment: Update the ConfigMap and allow the Operator to reconcile the changes.
9. Helm deployment: Apply your updated configuration using helm upgrade.
10. Verify the features are enabled. After the Red Hat Developer Hub instance restarts, confirm that the star icon and Quicklinks matrix appear in the global header.

Procedure

1. Specify the global.floatingactionbutton/config mount point in your app-config-dynamic.yaml file. For example:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-bulk-import:
             # Start of the floating action button configuration
             mountPoints:
               - mountPoint: global.floatingactionbutton/config
                 importName: BulkImportPage
                 config:
                   slot: 'page-end'
                   icon: <svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#e8eaed"><g><rect fill="none" height="24" width="24"/></g><g><path d="M11,7L9.6,8.4l2.6,2.6H2v2h10.2l-2.6,2.6L11,17l5-5L11,7z M20,19h-8v2h8c1.1,0,2-0.9,2-2V5c0-1.1-0.9-2-2-2h-8v2h8V19z"/></g></svg>
                   label: 'Bulk import'
                   toolTip: 'Register multiple repositories in bulk'
                   to: /bulk-import/repositories
             # End of the floating action button configuration
             appIcons:
               - name: bulkImportIcon
                 importName: BulkImportIcon
             dynamicRoutes:
               - path: /bulk-import/repositories
                 importName: BulkImportPage
                 menuItem:
                   icon: bulkImportIcon
                   text: Bulk import

   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.

2. 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:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-global-floating-action-button:
             mountPoints:
                 - mountPoint: application/listener
                   importName: DynamicGlobalFloatingActionButton
                 - mountPoint: global.floatingactionbutton/config
                   importName: NullComponent
                   config:
                     icon: '<svg viewBox="0 0 250 300" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid"><path d="M200.134 0l55.555 117.514-55.555 117.518h-47.295l55.555-117.518L152.84 0h47.295zM110.08 99.836l20.056-38.092-2.29-8.868L102.847 0H55.552l48.647 102.898 5.881-3.062zm17.766 74.433l-17.333-39.034-6.314-3.101-48.647 102.898h47.295l25-52.88v-7.883z" fill="#40B4E5"/><path d="M152.842 235.032L97.287 117.514 152.842 0h47.295l-55.555 117.514 55.555 117.518h-47.295zm-97.287 0L0 117.514 55.555 0h47.296L47.295 117.514l55.556 117.518H55.555z" fill="#003764"/></svg>'
                     label: 'Quay'
                     showLabel: true
                     toolTip: 'Quay'
                     to: 'https://quay.io'
                 - mountPoint: global.floatingactionbutton/config
                   importName: NullComponent
                   config:
                     icon: github
                     label: 'Git'
                     toolTip: 'Github'
                     to: https://github.com/redhat-developer/rhdh-plugins

   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.

3. 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:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-bulk-import:
             # Start of fab config
             mountPoints:
               - mountPoint: global.floatingactionbutton/config
                 importName: BulkImportPage
                 config:
                   slot: 'page-end'
                   icon: <svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#e8eaed"><g><rect fill="none" height="24" width="24"/></g><g><path d="M11,7L9.6,8.4l2.6,2.6H2v2h10.2l-2.6,2.6L11,17l5-5L11,7z M20,19h-8v2h8c1.1,0,2-0.9,2-2V5c0-1.1-0.9-2-2-2h-8v2h8V19z"/></g></svg>
                   label: 'Bulk import'
                   toolTip: 'Register multiple repositories in bulk'
                   to: /bulk-import/repositories
             # end of fab config
             appIcons:
               - name: bulkImportIcon
                 importName: BulkImportIcon
             dynamicRoutes:
               - path: /bulk-import/repositories
                 importName: BulkImportPage
                 menuItem:
                   icon: bulkImportIcon
                   text: Bulk import
   
   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-global-floating-action-button
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-global-floating-action-button:
             mountPoints:
               - mountPoint: application/listener
                 importName: DynamicGlobalFloatingActionButton
               - mountPoint: global.floatingactionbutton/config
                 importName: NullComponent
                 config:
                   icon: github
                   label: 'Git'
                   toolTip: 'Github'
                   to: https://github.com/redhat-developer/rhdh-plugins
               - mountPoint: global.floatingactionbutton/config
                 importName: NullComponent
                 config:
                   icon: '<svg viewBox="0 0 250 300" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid"><path d="M200.134 0l55.555 117.514-55.555 117.518h-47.295l55.555-117.518L152.84 0h47.295zM110.08 99.836l20.056-38.092-2.29-8.868L102.847 0H55.552l48.647 102.898 5.881-3.062zm17.766 74.433l-17.333-39.034-6.314-3.101-48.647 102.898h47.295l25-52.88v-7.883z" fill="#40B4E5"/><path d="M152.842 235.032L97.287 117.514 152.842 0h47.295l-55.555 117.514 55.555 117.518h-47.295zm-97.287 0L0 117.514 55.555 0h47.296L47.295 117.514l55.556 117.518H55.555z" fill="#003764"/></svg>'
                   label: 'Quay'
                   showLabel: true
                   toolTip: 'Quay'
                   to: 'https://quay.io'

   frontend:mountPoints:importName

   (Required) The import name with an associated component to the mount point.

4. 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:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-bulk-import:
             # start of fab config
             mountPoints:
               - mountPoint: global.floatingactionbutton/config
                 importName: BulkImportPage 1
                 config:
                   slot: 'page-end'
                   icon: <svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#e8eaed"><g><rect fill="none" height="24" width="24"/></g><g><path d="M11,7L9.6,8.4l2.6,2.6H2v2h10.2l-2.6,2.6L11,17l5-5L11,7z M20,19h-8v2h8c1.1,0,2-0.9,2-2V5c0-1.1-0.9-2-2-2h-8v2h8V19z"/></g></svg>
                   label: 'Bulk import'
                   toolTip: 'Register multiple repositories in bulk'
                   to: /bulk-import/repositories
                   visibleOnPaths: ['/catalog', '/settings']
             # end of fab config
             appIcons:
               - name: bulkImportIcon
                 importName: BulkImportIcon
             dynamicRoutes:
               - path: /bulk-import/repositories
                 importName: BulkImportPage
                 menuItem:
                   icon: bulkImportIcon
                   text: Bulk import

   frontend:mountPoints:importName

   Enter the import name with an associated component to the mount point.

5. 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:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import
     disabled: false
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-bulk-import:
             # start of fab config
             mountPoints:
               - mountPoint: global.floatingactionbutton/config
                 importName: BulkImportPage 1
                 config:
                   slot: 'page-end'
                   icon: <svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#e8eaed"><g><rect fill="none" height="24" width="24"/></g><g><path d="M11,7L9.6,8.4l2.6,2.6H2v2h10.2l-2.6,2.6L11,17l5-5L11,7z M20,19h-8v2h8c1.1,0,2-0.9,2-2V5c0-1.1-0.9-2-2-2h-8v2h8V19z"/></g></svg>
                   label: 'Bulk import'
                   toolTip: 'Register multiple repositories in bulk'
                   to: /bulk-import/repositories
                   excludeOnPaths: ['/bulk-import']
             # end of fab config
             appIcons:
               - name: bulkImportIcon
                 importName: BulkImportIcon
             dynamicRoutes:
               - path: /bulk-import/repositories
                 importName: BulkImportPage
                 menuItem:
                   icon: bulkImportIcon
                   text: Bulk import

   frontend:mountPoints:importName

   Enter the import name with an associated component to the mount point.

6. To configure translation support for the floating action button, use translation keys instead of static text. The Global Floating Action Button plugin supports internationalization (i18n) through the labelKey and toolTipKey properties.

   Example for using translation keys in dynamic configuration:

1. If the labelKey is provided, the plugin will attempt to resolve the translation key
2. If the translation key is found, it will be used as the label
3. If the translation key is not found, the plugin will fall back to the label property

Procedure

1. Enable RBAC in your app-config.yaml file:

   permission:
     enabled: true

   When RBAC is enabled, the system determines user roles based on permissions:

   • Users with policy.entity.create permission are assigned the admin role.

   • Users without this permission are assigned the developer role.

     Note

     If RBAC is disabled (permission.enabled: false) or not configured, users are assumed to be platform engineers setting up Red Hat Developer Hub (RHDH) and are assigned the admin role.

2. Configure quick start items with role assignments in your app-config.yaml file:

   app:
     quickstart:
       - title: 'Platform Configuration'
         titleKey: steps.platformConfiguration.title
         roles: ['admin']
         # Only admins see this
       - title: 'Getting Started as Developer'
         titleKey: steps.gettingStarted.title
         roles: ['developer']
         # Only developers see this
       - title: 'Universal Welcome Guide'
         titleKey: steps.universalWelcome.title
         roles: ['admin', 'developer']
         # Both user roles see this

   The following roles are supported:

   admin

   Platform engineers, administrators, and users with elevated permissions

   developer

   Regular developers and users with standard permissions

   Note

   Quick start items without a roles property default to the admin role. Items can specify multiple roles, and users see quick start items that match their assigned role.

Procedure

1. In your RHDH navigation menu, click the Help (?) icon.
2. In the dropdown menu, click Quick start.
3. Select the quick start step that you want to begin.

4. To close the quick start drawer, click Hide.

   
   Note

   Your overall progress is tracked and displayed as a progress bar and a progress percentage in the quick start footer.

Procedure

1. For all quick start steps (both existing and new) in your configuration file, you must define both the original text and the new localization keys. For example, in the quickstart section of your custom app-config.yaml file, add the titleKey, descriptionKey, and textKey values, as follows:

   app-config.yaml fragment

   app:
     quickstart:
       # Existing quick start steps should also be updated with keys
       - title: 'Setup Authentication'
         titleKey: steps.setupAuth.title
         description: 'Learn the basics of navigating the {product-short} interface'
         descriptionKey: steps.setupAuth.description
         icon: 'home'
         cta:
           text: 'Get Started'
           textKey: steps.setupAuth.ctaTitle
           link: '/catalog'
   # ...

   where:

   title

   (Mandatory) Fallback for the title.

   titleKey

   Key for the translated title.

   description

   (Mandatory) Fallback for the description.

   descriptionKey

   Key for the translated description.

   text

   (Mandatory) Fallback for the CTA text.

   textKey

   Key for the translated CTA text.

2. In your dynamic-plugins.yaml file, add the translationResources section to your red-hat-developer-hub-backstage-plugin-quickstart configuration, as follows:

   app-config.yaml fragment

   plugins:
     - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-quickstart
         disabled: false
         pluginConfig:
           dynamicPlugins:
             frontend:
               red-hat-developer-hub.backstage-plugin-quickstart:
                 # translationResources definition is required for translations to work
                 translationResources:
                   - importName: quickstartTranslations
                     ref: quickstartTranslationRef
                 # ... other configurations like mountPoints ...

   where:

   importName

   Enter the name used to reference the import.

   ref

   Reference to the resource definition.

3. In your translation file, map the keys from the first step to the localized strings for each supported language.

   allTranslations.json fragment

   "plugin.quickstart": {
     "en": {
       "steps.setupAuth.title": "Manage plugins EN",
       "steps.setupAuth.description": "EN Browse and install extensions to add features, connect with external tools, and customize your experience.",
       "steps.setupAuth.ctaTitle": "Start"
     },
     "fr": {
       "steps.setupAuth.title": "Gérer les plugins FR",
       "steps.setupAuth.description": "FR Parcourez et installez des extensions pour ajouter des fonctionnalités, vous connecter à des outils externes et personnaliser votre expérience.",
       "steps.setupAuth.ctaTitle": "Commencer"
     }
   }

Procedure

1. Publish the JSON file containing your Tech Radar data to a web server, such as GitHub or GitLab. You can find an example at https://raw.githubusercontent.com/backstage/community-plugins/main/workspaces/tech-radar/plugins/tech-radar-common/src/sampleTechRadarResponse.json.

2. Configure Developer Hub to access the Tech Radar data from the hosted JSON files, by adding the following to the app-config.yaml file:

   techRadar:
     url: <tech_radar_data_url>

   <tech_radar_data_url>

   Enter the Tech Radar data hosted JSON URL.

Procedure

1. Deploy your Developer Hub customization service on the same OpenShift Container Platform cluster as your Developer Hub instance. You can find an example at red-hat-developer-hub-customization-provider, that provides the same data as default Developer Hub data. The customization service provides a Tech Radar data URL such as: http://<rhdh-customization-provider>/tech-radar.

2. Add the dedicated service as an allowed host by adding the following code to the app-config.yaml file:

   backend:
      reading:
           allow:
             - host: '<rhdh_customization_provider_base_url>'

   <rhdh_customization_provider_base_url>

   Enter the base URL of your Tech Radar data URL, such as: <rhdh-customization-provider>.

3. Add the following to the app-config.yaml file:

   techRadar:
       url: <tech_radar_data_url>

   <tech_radar_data_url>

   Enter your Tech Radar data URL, such as: http://<rhdh-customization-provider>/tech-radar.

Procedure

1. From the Developer Hub web console, click Settings.

2. From the Appearance panel, select Light, Dark, or Auto to change the theme mode.

   

Procedure

1. Export a theme provider function in your dynamic plugin, for example:

   import { lightTheme } from './lightTheme'; // some custom theme
   import { UnifiedThemeProvider } from '@backstage/theme';
   export const lightThemeProvider = ({ children }: { children: ReactNode }) => (
     <UnifiedThemeProvider theme={lightTheme} children={children} />
   );

   For more information about creating a custom theme, see Backstage documentation - Creating a Custom Theme.

2. Configure Developer Hub to load the theme in the UI by using the themes configuration field:

   dynamicPlugins:
     frontend:
       example.my-custom-theme-plugin:
         themes:
           - id: light
             title: Light
             variant: light
             icon: someIconReference
             importName: lightThemeProvider

   id

   Enter your theme ID, such as my_theme. Enter dark to override the default Developer Hub dark theme. Enter light to override the default Developer Hub light theme.

Procedure

1. Identify your user personas and their workflow needs.

   Plan which types of content each persona requires on their homepage.

   Example persona planning:

   Persona	Primary Tasks	Needed Homepage Content
   Developer	Write code, deploy services, review PRs	Templates, catalog, quick access to repos
   Manager	Monitor team progress, review metrics	Dashboards, reports, team activity
   Data Scientist	Run experiments, access data	Notebooks, data sources, model registry

2. Open your app-config.yaml configuration file.

3. Define the homepage layout structure for each persona in the homepage.defaultWidgets section.

   For example, configure a developer persona homepage with cards appropriate for development workflows:

   homepage:
     defaultWidgets:
       # Developer persona layout
       - id: developer-onboarding
         ref: 'rhdh-onboarding-section'
         layout:
           xl: { w: 12, h: 6 }
           lg: { w: 12, h: 6 }
   
       - id: developer-quickaccess
         ref: quickaccess-card
         props:
           title: Developer Quick Access
         layout:
           xl: { w: 7, h: 8 }
           lg: { w: 7, h: 8 }
   
       - id: templates
         ref: rhdh-template-section
         layout:
           xl: { w: 12, h: 5 }
           lg: { w: 12, h: 5 }
   
       - id: starred-entities
         ref: catalog-starred-entities-card
         layout:
           xl: { w: 5, h: 4, x: 7 }
           lg: { w: 5, h: 4, x: 7 }

   The layout uses a 12-column grid system with properties:

   1. w (width): Number of columns (1-12)
   2. h (height): Number of grid rows
   3. x (x-position): Column offset (0-11)
   4. y (y-position): Row offset (optional)

4. Configure a default homepage layout that all users can see.

   Create cards without visibility conditions so that all authenticated users see essential homepage content:

       # Default cards visible to all users
       - id: onboarding
         ref: 'rhdh-onboarding-section'
         layout:
           xl: { w: 12, h: 6 }
   
       - id: quickaccess-card
         ref: quickaccess-card
         layout:
           xl: { w: 6, h: 6 }

5. Save the configuration file.

   Note

   The layouts you authored are not yet restricted to specific user groups. To control which personas see which layouts, proceed to attach these layouts to RBAC groups.

Procedure

1. Enable the homepage backend plugin.

   Important

   These features are for Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

   For more information on Red Hat Technology Preview features, see Technology Preview Features Scope.

   Add the following configuration to your dynamic-plugins.yaml file:

   plugins:
     - package: oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-homepage-backend:1.10!red-hat-developer-hub-backstage-plugin-homepage-backend
       disabled: false

2. Identify your user personas and their corresponding groups.

   Important

   Replace the example group names below with your organization’s actual group names.

   Persona	Group
   Developer	group:default/developers
   Manager	group:default/managers
   Data Scientist	group:default/data-scientists

3. Verify that you created the groups in your RHDH configuration.

   Check that the groups exist by using the RBAC web UI or by reviewing your RBAC configuration file. You must create all groups referenced in your persona mapping before configuring homepage visibility.

4. Open your app-config.yaml configuration file.

5. Attach persona-specific layouts to groups by adding the if.groups field to group cards under a shared visibility condition.

   For example, attach the developer persona layout to the developers group:

   homepage:
     defaultWidgets:
       # Attach developer layout to developers group
       - if:
           groups: [group:default/developers]
         children:
           - id: developer-onboarding
             ref: 'rhdh-onboarding-section'
             layout:
               xl: { w: 12, h: 6 }
               lg: { w: 12, h: 6 }
   
           - id: developer-quickaccess
             ref: quickaccess-card
             props:
               title: Developer Quick Access
             layout:
               xl: { w: 7, h: 8 }
               lg: { w: 7, h: 8 }
   
           - id: templates
             ref: rhdh-template-section
             layout:
               xl: { w: 12, h: 5 }
               lg: { w: 12, h: 5 }
   
           - id: starred-entities
             ref: catalog-starred-entities-card
             layout:
               xl: { w: 5, h: 4, x: 7 }
               lg: { w: 5, h: 4, x: 7 }

   The groups field accepts an array of group entity references. Users who belong to any of the listed groups see all child cards.

6. Control visibility for multiple groups by adding additional if.groups configurations.

   Individual child cards can include their own if conditions to further restrict visibility beyond the parent group’s rules.

   Note

   The front-end positions cards according to layout coordinates (x, y, w, h), not array order. The configuration array order does not affect rendering position.

7. Save the configuration file and restart Red Hat Developer Hub:

   $ kubectl rollout restart deployment/<rhdh-deployment-name>

   Replace <rhdh-deployment-name> with the name of your RHDH deployment.

   Important

   RHDH validates the homepage configuration at startup. If the configuration contains errors, RHDH will fail to start. Check the pod logs for configuration validation errors if the deployment does not become ready.

Verification

1. Log in to Red Hat Developer Hub as a test user who belongs to one of the configured groups.

   The homepage displays only the cards configured for that user’s persona.

2. Log in as a test user from a different group.

   The homepage displays a different set of cards based on the second user’s group membership.

3. Log in as a test user who does not belong to any persona-specific group.

   The homepage displays only the default cards that have no if conditions.

Procedure

1. Optional: For persona-based homepage configuration with group-based visibility controls, enable the homepage backend plugin.

   Important

   These features are for Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

   For more information on Red Hat Technology Preview features, see Technology Preview Features Scope.

   Add the following configuration to your dynamic-plugins.yaml file:

   plugins:
     - package: oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-homepage-backend:1.10!red-hat-developer-hub-backstage-plugin-homepage-backend
       disabled: false

   Note

   The homepage backend plugin is only required for persona-based layouts with group-based visibility controls (the if.groups field). Basic homepage customization does not require the backend plugin.

2. Configure different cards for your Home page in Red Hat Developer Hub as shown in the following code:

   Search

   You can use the SearchBar card to provide essential search functionality directly on the Home page.

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         mountPoints:
           - mountPoint: home.page/cards
             importName: SearchBar
             config:
               layouts:
                 xl: { w: 10, h: 1, x: 1 }
                 lg: { w: 10, h: 1, x: 1 }
                 md: { w: 10, h: 1, x: 1 }
                 sm: { w: 10, h: 1, x: 1 }
                 xs: { w: 12, h: 1 }
                 xxs: { w: 12, h: 1 }
               props:
                 path: /search
                 queryParam: query

   Prop	Default	Description
   path	/search	Override the linked search path if needed
   queryParam	query	Override the search query parameter name if needed

   Quick access

   You can use the QuickAccessCard card to function as a customizable shortcut panel.

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         mountPoints:
           - mountPoint: home.page/cards
             importName: QuickAccessCard
             config:
               layouts:
                 xl: { h: 8 }
                 lg: { h: 8 }
                 md: { h: 8 }
                 sm: { h: 8 }
                 xs: { h: 8 }
                 xxs: { h: 8 }
               props:
                 title: Quick Access
                 path: /quickaccess

   Prop	Default	Description
   title	Quick Access	Override the linked search path if needed
   path	none	Override the search query parameter name if needed

   Headline

   You can use the Headline card to display important information.

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         mountPoints:
           - mountPoint: home.page/cards
             importName: Headline
             config:
               layouts:
                 xl: { h: 1 }
                 lg: { h: 1 }
                 md: { h: 1 }
                 sm: { h: 1 }
                 xs: { h: 1 }
                 xxs: { h: 1 }
               props:
                 title: Important info

   Prop	Default	Description
   title	none	Title

   Markdown

   You can use the Markdown card to display richly formatted content directly within the Home page layout. This card uses Markdown syntax to present structured information, such as lists and links (documentation and plugin repositories).

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         mountPoints:
           - mountPoint: home.page/cards
             importName: MarkdownCard
             config:
               layouts:
                 xl: { w: 6, h: 4 }
                 lg: { w: 6, h: 4 }
                 md: { w: 6, h: 4 }
                 sm: { w: 6, h: 4 }
                 xs: { w: 6, h: 4 }
                 xxs: { w: 6, h: 4 }
               props:
                 title: Company links
                 content: |
                   ### RHDH
                   * [Website](https://developers.redhat.com/rhdh/overview)
                   * [Documentation](https://docs.redhat.com/en/documentation/red_hat_developer_hub/)
                   * [Backstage Community Plugins](https://github.com/backstage/community-plugins)
                   * [RHDH Plugins](https://github.com/redhat-developer/rhdh-plugins)
                   * [RHDH Hub](https://github.com/redhat-developer/rhdh)
           - mountPoint: home.page/cards
             importName: Markdown
             config:
               layouts:
                 xl: { w: 6, h: 4, x: 6 }
                 lg: { w: 6, h: 4, x: 6 }
                 md: { w: 6, h: 4, x: 6 }
                 sm: { w: 6, h: 4, x: 6 }
                 xs: { w: 6, h: 4, x: 6 }
                 xxs: { w: 6, h: 4, x: 6 }
               props:
                 title: Important company links
                 content: |
                   ### RHDH
                   * [Website](https://developers.redhat.com/rhdh/overview)
                   * [Documentation](https://docs.redhat.com/en/documentation/red_hat_developer_hub/)
                   * [Documentation](https://docs.redhat.com/en/documentation/red_hat_developer_hub/)
                   * [Backstage Community Plugins](https://github.com/backstage/community-plugins)
                   * [RHDH Plugins](https://github.com/redhat-developer/rhdh-plugins)
                   * [RHDH Hub](https://github.com/redhat-developer/rhdh)

   Placeholder

   You can use the Placeholder card as a utility element for reserving space or for layout testing on the Home page.

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         mountPoints:
           - mountPoint: home.page/cards
             importName: Placeholder
             config:
               layouts:
                 xl: { w: 1, h: 1 }
                 lg: { w: 1, h: 1 }
                 md: { w: 1, h: 1 }
                 sm: { w: 1, h: 1 }
                 xs: { w: 1, h: 1 }
                 xxs: { w: 1, h: 1 }
               props:
                 showBorder: true
                 debugContent: '1'

   Catalog starred entities

   You can use the CatalogStarredEntitiesCard card to provide a dedicated space on the Home page for users to view catalog entities that they have marked as starred.

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         mountPoints:
           - mountPoint: home.page/cards
             importName: CatalogStarredEntitiesCard

   Featured docs

   You can use the FeaturedDocsCard card as a way to highlight specific documentation within Red Hat Developer Hub, as it is available for deployment on the Home page.

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         mountPoints:
           - mountPoint: home.page/cards
             importName: FeaturedDocsCard

   EntitySection

   You can use the EntitySection card to create a visually engaging section that highlights catalog entities of various kinds, such as Component, API, Resource, and System.

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         mountPoints:
           - mountPoint: home.page/cards
             importName: EntitySection
             config:
               layouts:
                 xl: { w: 12, h: 6 }
                 lg: { w: 12, h: 6 }
                 md: { w: 12, h: 6 }
                 sm: { w: 12, h: 6 }
                 xs: { w: 12, h: 6 }
                 xxs: { w: 12, h: 14.5 }

   OnboardingSection

   You can use the OnboardingSection card to quickly discover learning resources within RHDH.

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         mountPoints:
           - mountPoint: home.page/cards
             importName: OnboardingSection
             config:
               layouts:
                 xl: { w: 12, h: 5 }
                 lg: { w: 12, h: 5 }
                 md: { w: 12, h: 5 }
                 sm: { w: 12, h: 5 }
                 xs: { w: 12, h: 7 }
                 xxs: { w: 12, h: 12 }

   TemplateSection

   You can use the TemplateSection card to quickly explore and initiate software templates in RHDH.

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         mountPoints:
           - mountPoint: home.page/cards
             importName: TemplateSection
             config:
               layouts:
                 xl: { w: 12, h: 5 }
                 lg: { w: 12, h: 5 }
                 md: { w: 12, h: 5 }
                 sm: { w: 12, h: 5 }
                 xs: { w: 12, h: 5 }
                 xxs: { w: 12, h: 14 }

Procedure

1. Configure your Developer Hub app-config.yaml configuration file by choosing one of the following options:

   1. Use the full space on smaller windows and half of the space on larger windows as follows:

      dynamicPlugins:
        frontend:
          red-hat-developer-hub.backstage-plugin-dynamic-home-page:
            mountPoints:
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 6, h: 2 }
                    lg: { w: 6, h: 2 }
                    md: { w: 6, h: 2 }
                    sm: { w: 12, h: 2 }
                    xs: { w: 12, h: 2 }
                    xxs: { w: 12, h: 2 }
                  props:
                    showBorder: true
                    debugContent: a placeholder

   2. Show the cards side by side by defining the x parameter as shown in the following example:

      dynamicPlugins:
        frontend:
          red-hat-developer-hub.backstage-plugin-dynamic-home-page:
            mountPoints:
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 6, h: 2 }
                    lg: { w: 6, h: 2 }
                    md: { w: 6, h: 2 }
                    sm: { w: 12, h: 2 }
                    xs: { w: 12, h: 2 }
                    xxs: { w: 12, h: 2 }
                  props:
                    showBorder: true
                    debugContent: left
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 6, h: 2, x: 6 }
                    lg: { w: 6, h: 2, x: 6 }
                    md: { w: 6, h: 2, x: 6 }
                    sm: { w: 12, h: 2, x: 0 }
                    xs: { w: 12, h: 2, x: 0 }
                    xxs: { w: 12, h: 2, x: 0 }
                  props:
                    showBorder: true
                    debugContent: right

      However, you can see a second card below this card by default.

   3. Show the cards in three columns by defining the x parameter as shown in the following example:

      dynamicPlugins:
        frontend:
          red-hat-developer-hub.backstage-plugin-dynamic-home-page:
            mountPoints:
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 4, h: 2 }
                    lg: { w: 4, h: 2 }
                    md: { w: 4, h: 2 }
                    sm: { w: 6, h: 2 }
                    xs: { w: 12, h: 2 }
                    xxs: { w: 12, h: 2 }
                  props:
                    showBorder: true
                    debugContent: left
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 4, h: 2, x: 4 }
                    lg: { w: 4, h: 2, x: 4 }
                    md: { w: 4, h: 2, x: 4 }
                    sm: { w: 6, h: 2, x: 6 }
                    xs: { w: 12, h: 2 }
                    xxs: { w: 12, h: 2 }
                  props:
                    showBorder: true
                    debugContent: center
              - mountPoint: home.page/cards
                importName: Placeholder
                config:
                  layouts:
                    xl: { w: 4, h: 2, x: 8 }
                    lg: { w: 4, h: 2, x: 8 }
                    md: { w: 4, h: 2, x: 8 }
                    sm: { w: 6, h: 2 }
                    xs: { w: 12, h: 2 }
                    xxs: { w: 12, h: 2 }
                  props:
                    showBorder: true
                    debugContent: right

Procedure

1. You can arrange the cards and adjust their dimensions using the drag-and-drop and resize functionality. The following is an example of an interactive homepage where you can add, remove, move, and resize cards:

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         dynamicRoutes:
           - path: /
             importName: DynamicCustomizableHomePage
         mountPoints:
            - mountPoint: home.page/cards
              importName: OnboardingSection
              config:
               layouts:
                 xl: { w: 12, h: 6 }
                 lg: { w: 12, h: 6 }
                 md: { w: 12, h: 7 }
                 sm: { w: 12, h: 8 }
                 xs: { w: 12, h: 9 }
                 xxs: { w: 12, h: 14 }
           - mountPoint: home.page/cards
             importName: EntitySection
             config:
               layouts:
                 xl: { w: 12, h: 7 }
                 lg: { w: 12, h: 7 }
                 md: { w: 12, h: 8 }
                 sm: { w: 12, h: 9 }
                 xs: { w: 12, h: 11 }
                 xxs: { w: 12, h: 15 }
           - mountPoint: home.page/cards
             importName: TemplateSection
             config:
               layouts:
                 xl: { w: 12, h: 5 }
                 lg: { w: 12, h: 5 }
                 md: { w: 12, h: 5 }
                 sm: { w: 12, h: 5 }
                 xs: { w: 12, h: 7.5 }
                 xxs: { w: 12, h: 13.5 }
           # Additional cards available in "Add widget" dialog
           - mountPoint: home.page/cards
             importName: RecentlyVisitedCard
           - mountPoint: home.page/cards
             importName: TopVisitedCard

2. You can change the title by overriding the title property of the dynamic homepage plugin as shown in the following example:

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         dynamicRoutes:
           - path: /
             importName: DynamicHomePage # or DynamicCustomizableHomePage for customizable homepage
             config:
               props:
                 title: 'Howdy {{firstName}} or {{displayName}}'

   The title property supports two variables:

3. {{displayName}}: This contains the full displayName of the catalog entity.
4. {{firstName}}: This contains the first part (separated by a space) of the displayName.

5. You can use a subtitle property which is not used by default as shown in the following example:

   dynamicPlugins:
     frontend:
       red-hat-developer-hub.backstage-plugin-dynamic-home-page:
         dynamicRoutes:
           - path: /
             importName: DynamicHomePage # or DynamicCustomizableHomePage
             config:
               props:
                 title: Our custom RHDH instance
                  subtitle: 'Hello {{displayName}}'

Procedure

1. Add the JSON Data source. The QuickAccessCard card on the homepage supports loading data from a JSON file. This JSON file can be hosted in your GitHub repository or any accessible endpoint.

2. Configure the Proxy in your RHDH app-config.yaml file.

   To allow the homepage to fetch data from the hosted JSON file, add the following proxy configuration to your RHDH app-config.yaml file:

   proxy:
     endpoints:
     # customize your backstage instance
     '/developer-hub':
       target: https://raw.githubusercontent.com/ # For example, https://raw.githubusercontent.com/
       pathRewrite:
         '^/api/proxy/developer-hub$': <path_to_your>.json # For example, /redhat-developer/rhdh/main/packages/app/public/homepage/data.json
       changeOrigin: true
       secure: true

   The following table lists the supported icon types:

   Icon type	Example	Rendered as
   Backstage system icon	"catalog"	Uses Backstage system [icons](https://github.com/backstage/backstage/blob/master/packages/app-defaults/src/defaults/icons.tsx)
   SVG String	"<svg>…​</svg>"	Renders inline SVG
   Image URL	"https://example.com/icon.png"	Renders external image. External images might be restricted to Content Security Policy (CSP) which can be configured in your RHDH app-config.yaml file.
   Relative Path	"/homepage/icons/icon.png"	Loads the icon from the app public folder (if present)

   Note

   SVGs must be valid strings when stored inside JSON (use single quotes inside <svg>).

   The following is an example of a JSON file:

   [
    {
    "title": "Community",
    "isExpanded": true,
    "links": [
    {
    "iconUrl": "https://img.icons8.com/ios/50/globe--v1.png",
    "label": "Website",
    "url": "https://developers.redhat.com/"
    },
    {
    "iconUrl": "https://img.icons8.com/ios/50/link--v1.png",
    "label": "Blog",
    "url": "https://developers.redhat.com/blog"
    },
    {
    "iconUrl": "github",
    "label": "GitHub",
    "url": "https://github.com/redhat-developer"
    },
    {
    "iconUrl": "https://img.icons8.com/color/48/slack.png",
    "label": "Slack",
    "url": "https://join.slack.com/xyz"
    },
    {
    "iconUrl": "https://img.icons8.com/color/48/youtube-squared.png",
    "label": "Videos for developers",
    "url": "https://developers.redhat.com/videos"
    },
    {
    "iconUrl": "<svg xmlns='http://www.w3.org/2000/svg' xml:space='preserve' width='2048' height='2048' style='shape-rendering:geometricPrecision;text-rendering:geometricPrecision;image-rendering:optimizeQuality;fill-rule:evenodd;clip-rule:evenodd'><defs><style>.fil0{fill:none}.fil4{fill:#bdbdbd;fill-rule:nonzero}</style></defs><g id='Layer_x0020_1'><path class='fil0' d='M0 0h2048v2048H0z'/><path class='fil0' d='M255.999 255.999h1536v1536h-1536z'/><path class='fil0' d='M256 256h1536v1536H256z'/><g id='_342647616'><path id='_342648000' style='fill:#e53935;fill-rule:nonzero' d='m273.04 666.226 737.28-367.843 13.68-6.824 13.68 6.824 737.28 367.843 17.04 8.503v234.834L993.281 1418.52 255.999 909.563V674.729z'/><path id='_342647880' style='fill:#fff' d='M609.28 711.961h829.439V1541.4H609.28z'/><path id='_342647808' style='fill:#c62828;fill-rule:nonzero' d='m1024 1279.73 723.6-361.079 44.4-22.156v859.945H255.999V896.495l44.402 22.156z'/><path id='_342647736' class='fil4' d='M1331.2 896.285H716.716v-61.442H1331.2z'/><path id='_342647688' class='fil4' d='M1203.22 1049.88H844.698v-61.439h358.522z'/></g></g></svg>",
    "label": "Mailing List",
    "url": "https://groups.google.com/g/xyz"
    },
    ]
   }
   ]

Procedure

1. In the Red Hat OpenShift Container Platform web console, click +Add > Import from Git.

2. Enter the URL of your Git repository into the Git Repo URL field.

   To use the red-hat-developer-hub-customization-provider service, add the URL for the red-hat-developer-hub-customization-provider repository or your fork of the repository containing your customizations.

3. On the General tab, enter red-hat-developer-hub-customization-provider in the Name field and click Create.

4. On the Advanced Options tab, copy the value from Target Port.

   Note

   Target Port automatically generates a Kubernetes or OpenShift Container Platform service to communicate with.

5. Add the following code to the app-config.yaml file:

   proxy:
     endpoints:
       # Other Proxies
       # customize developer hub instance
       '/developer-hub':
         target: ${HOMEPAGE_DATA_URL} # For example: http://<SERVICE_NAME>:8080, such as http://rhdh-customization-provider:8080
         changeOrigin: true
         # Change to "false" in case of using self-hosted cluster with a self-signed certificate
         secure: true

   Note

   The red-hat-developer-hub-customization-provider service contains the 8080 port by default. If you are using a custom port, you can specify it with the 'PORT' environmental variable in the app-config.yaml file.

6. Replace the HOMEPAGE_DATA_URL by adding the URL to rhdh-secrets or by directly replacing it in your custom ConfigMap.
7. Delete the Developer Hub pod to ensure that the new configurations are loaded correctly.

Verification

1. To view the service, go to the OpenShift Container Platform web console and click Networking > Service.

   Note

   You can also view Service Resources in the Topology view.

2. Ensure that the provided API URL for the Home page returns the data in JSON format as shown in the following example:

   [
     {
       "title": "Dropdown 1",
       "isExpanded": false,
       "links": [
         {
           "iconUrl": "https://imagehost.com/image.png",
           "label": "Dropdown 1 Item 1",
           "url": "https://example.com/"
         },
         {
           "iconUrl": "https://imagehost2.org/icon.png",
           "label": "Dropdown 1 Item 2",
           "url": ""
         }
       ]
     },
     {
       "title": "Dropdown 2",
       "isExpanded": true,
       "links": [
         {
           "iconUrl": "http://imagehost3.edu/img.jpg",
           "label": "Dropdown 2 Item 1",
           "url": "http://example.com"
         }
       ]
     }
   ]

   Note

   If the request call fails or is not configured, the Developer Hub instance falls back to the default local data.

3. 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:

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: app-config.yaml
   data:
     app-config.yaml: |
       app:
         title: Red Hat Developer Hub
       backend:
         csp:
           connect-src:
             - "'self'"
             - 'http:'
             - 'https:'
           img-src:
             - "'self'"
             - 'data:'
             - <image host url 1>
             - <image host url 2>
             - <image host url 3>
       # Other Configurations

Procedure

1. Create a JSON file containing the translation strings that you want to override, as shown in the following example. Supported languages include English (default), French, German, Italian, Japanese and Spanish.

   allTranslations.json fragment with translation string overrides

   {
     "plugin.global-floating-action-button": {
       "en": {
         "fab.quay.label": "QUAY EN JSON",
         "fab.rbac.label": "RBAC EN JSON",
         "fab.rbac.tooltip": "RBAC EN tooltip JSON"
       },
       "fr": {
         "fab.quay.label": "QUAY French JSON",
         "fab.quay.tooltip": "QUAY french tooltip JSON",
         "fab.rbac.label": "RBAC French JSON",
         "fab.rbac.tooltip": "RBAC french tooltip JSON"
       }
     },
     "plugin.global-header": {
       "en": {
         "applicationLauncher.developerHub": "{product-short} EN JSON"
       },
       "fr": {
         "applicationLauncher.developerHub": "{product-short} French JSON"
       }
     }
   }

2. Log in to your cluster and create a config map for your translations override strings:

   $ oc create configmap all-translations \
       --from-file=/<path_to>/allTranslations.json

3. Update your deployment configuration based on your installation method:

   Note

   As shown in the following examples, we recommend that you use the same mount path for your allTranslations.json file and any other override files that you create, for example /opt/app-root/src/translations.

   1. For an Operator-installed RHDH instance, update your Backstage custom resource (CR). For more information about configuring a CR, see Using the Red Hat Developer Hub Operator to run Developer Hub with your custom configuration.

      1. In the spec.application.extraFiles section, add the translations custom app configuration as shown in the following example:

         Backstage custom resource fragment

         apiVersion: rhdh.redhat.com/v1alpha5
         kind: {product-custom-resource-type}
         spec:
           application:
             extraFiles:
               mountPath: /opt/app-root/src/translations
               configMaps:
                 - name: all-translations

   2. For a Helm-installed RHDH instance, update your Developer Hub Backstage Helm chart to mount in the Developer Hub filesystem your files from the all-translations config map:

      1. In the Developer Hub Helm chart, go to Root Schema → Backstage chart schema → Backstage parameters → Backstage container additional volume mounts.

      2. Select Add Backstage container additional volume mounts and add the following values:

         mountPath

         /opt/app-root/src/translations

         name

         all-translations

      3. Add the translations to the Backstage container additional volumes in the Developer Hub Helm chart:

         name

         all-translations

         configMap

         defaultMode

         420

         name

         all-translations

4. Update the i18n section to your custom Developer Hub app-config.yaml configuration file to include the following translation override file:

   app-config.yaml fragment with localization i18n fields

   i18n:
     locales: # List of supported locales. Must include en, otherwise the translation framework will fail to load.
       - en
       - fr
       - de
       - it
       - ja
       - es
     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
       - /opt/app-root/src/translations/all-translations.json

Procedure

1. Create the following translation files in your plugin’s src/translations/ directory:

   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,
   });

   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;

   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;

   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 };

2. Create translation hooks file, as follows:

   import { useTranslationRef } from "@backstage/core-plugin-api/alpha";
   import { myPluginTranslationRef } from "../translations";
   
   export const useTranslation = () => useTranslationRef(myPluginTranslationRef);

3. Update your plugin components to replace hard-coded strings with translation calls as shown in the following example:

   const MyComponent = () => {
    return (
      <div>
        <h1>My Plugin</h1>
        <button>Export CSV</button>
      </div>
    );
   };

   import { useTranslation } from '../hooks/useTranslation';
   
   const MyComponent = () => {
    const { t } = useTranslation();
   
    return (
      <div>
        <h1>{t('page.title')}</h1>
        <button>{t('common.exportCSV')}</button>
      </div>
    );
   };

4. (Optional) If your content contains variables, use interpolation:

   // In your translation files
   'table.pagination.topN': 'Top {{count}} items'
   
   // In your component
   const { t } = useTranslation();
   const message = t('table.pagination.topN', { count: '10' });

5. (Optional) If your content contains dynamic translation keys (for example, from your plugin 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 (
      <div>
        <h2>{t(config.titleKey as any)}</h2>
        {/* Use 'as any' for dynamic keys */}
      </div>
    );
   };

6. Export the translation resources

   // Export your plugin
   export { myPlugin } from "./plugin";
   
   // Export translation resources for the application
   export { myPluginTranslations, myPluginTranslationRef } from "./translations";

7. Update your dynamic-plugins.default.yaml file, as follows:

   backstage-community.plugin-my-plugin:
    translationResources:
      - importName: myPluginTranslations
        ref: myPluginTranslationRef
        module: Alpha

8. Update your package.json file as follows:

   "exports": {
       ".": "./src/index.ts",
       "./alpha": "./src/alpha.ts",
       "./package.json": "./package.json"
     },
     "main": "src/index.ts",
     "types": "src/index.ts",
     "typesVersions": {
       "*": {
         "alpha": [
           "src/alpha.ts"
         ],
         "package.json": [
           "package.json"
         ]
       }
     }

Procedure

1. From the Developer Hub web console, click the down arrow next to your profile name, then click Settings.

2. From the Appearance panel, click the language dropdown to select your language of choice.

   

Procedure

1. In the app-config.yaml file, set the authentication environment to development:

   auth:
     environment: development

2. Restart the Developer Hub application to apply the changes.

Verification

1. Go to the login page of your Developer Hub instance.
2. Verify that the option to log in as a guest is available.

Procedure

1. In the app-config.yaml file, set the authentication environment to production:

   auth:
     environment: production

2. Restart the Developer Hub application to apply the changes.

Verification

1. Go to the login page of your Developer Hub instance.
2. Verify that the option to log in as a guest is no longer available.

Procedure

1. Register your Developer Hub app in RHBK:

   1. Use an existing realm, or create a realm, with a distinctive Name such as <my_realm>. Save the value for the next step:

2. RHBK realm base URL, such as: <your_rhbk_URL>/realms/<your_realm>.

   1. In the created realm, secure the first application, with:

      1. Client ID: A distinctive client ID, such as <RHDH>.
      2. Valid redirect URIs: Set to the OIDC handler URL: https://<my_developer_hub_domain>/api/auth/oidc/handler/frame.
      3. Go to the Credentials tab and copy the Client secret.
      4. Save the values for the next step:
3. Client ID

4. Client Secret

   1. In the same realm, get the credential information for an existing user or create a user. Save the user credential information for the verification steps.
5. Create a long, complex, and unique string to use as the Developer Hub session secret key.

6. Add the following key-value pairs to your Developer Hub secrets. You can use these secrets in the Developer Hub configuration files by using their environment variable name.

   KEYCLOAK_CLIENT_ID

   Enter the saved Client ID.

   KEYCLOAK_CLIENT_SECRET

   Enter the saved Client Secret.

   KEYCLOAK_BASE_URL

   Enter the saved RHBK realm base URL.

   KEYCLOAK_REALM

   Enter the realm name to provision users.

   KEYCLOAK_LOGIN_REALM

   Enter the realm name to authenticate users.

   SESSION_SECRET

   Enter the created session secret key.

Procedure

1. Collect the following LDAP credentials from your LDAP server:

   LDAP URL

   Your LDAP server URL, such as ldaps://ds.example.net.

   Bind DN

   Your bind distinguished name, such as cn=admin,OU=Users,DC=rhdh,DC=test.

   LDAP secret

   Your LDAP secret.

2. Optional: To use a secure LDAP connection (ldaps://), store your LDAP certificates in the ldap_certs.pem file and your LDAP keys in the ldap_keys.pem file.

   Warning

   In production mode, use a secure LDAP connection.

3. Add the LDAP_SECRET key-value pair to your Developer Hub secrets. You can use this secret in the Developer Hub configuration files by using its environment variable name.

   LDAP_SECRET

   Enter your LDAP secret.

4. Optional: To use a secure LDAP connection (ldaps://), add your LDAP certificates and keys files to a an OpenShift secret.

   $ oc create secret generic my-rhdh-ldap-secrets \
       --from-file=./ldap_certs.pem \
       --from-file=./ldap_keys.pem

Procedure

1. Create a GitHub App for integration.

   Note

   Use a GitHub App instead of an OAuth app to use fine-grained permissions and 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.

   1. Register a GitHub App with the following configuration:

      GitHub App name

      Enter a unique name identifying your GitHub App, such as integrating-with-rhdh-<GUID>.

      Homepage URL

      Enter your Developer Hub URL: https://<my_developer_hub_domain>.

      Webhook

      Clear "Active".

      Repository permissions

      Contents

      Read-only

      Commit statuses

      Read-only

      Organization permissions

      Members

      Read-only

      Where can this GitHub App be installed?

      Select Only on this account.

   2. In the General → Clients secrets section, click Generate a new client secret.
   3. In the General → Private keys section, click Generate a private key.
   4. In the Install App tab, choose an account to install your GitHub App on.
   5. Save the following values for the next step:
2. App ID
3. Client ID
4. Client secret
5. Private key

6. Store the integration app credentials: Add the following key/value pairs to your Developer Hub secrets.

   GITHUB_APP_APP_ID

   Enter the saved App ID.

   GITHUB_APP_CLIENT_ID_INTEGRATION

   Enter the saved Client ID.

   GITHUB_APP_CLIENT_SECRET_INTEGRATION

   Enter the saved Client Secret.

   GITHUB_APP_PRIVATE_KEY

   Enter the saved Private key.

   GITHUB_URL

   Enter the GitHub host domain: https://github.com.

   GITHUB_ORG

   Enter your GitHub organization name, such as <your_github_organization_name>.

7. Create a separate GitHub App for authentication.

   1. Register a GitHub App with the following configuration:

      GitHub App name

      Enter a unique name identifying your GitHub App, such as authenticating-with-rhdh-<GUID>.

      Homepage URL

      Enter your Developer Hub URL: https://<my_developer_hub_domain>.

      Authorization callback URL

      Enter your Developer Hub authentication backend URL: https://<my_developer_hub_domain>/api/auth/github/handler/frame.

      Webhook

      Clear "Active".

      Organization permissions

      Enable Read-only access to Members.

      Where can this GitHub App be installed?

      Select Only on this account.

   2. In the General → Clients secrets section, click Generate a new client secret.
   3. Save the following values for the next step:
8. Client ID
9. Client secret

10. Store the authentication app credentials: Add the following key/value pairs to your Developer Hub secrets.

    GITHUB_APP_CLIENT_ID

    Enter the saved Client ID.

    GITHUB_APP_CLIENT_SECRET

    Enter the saved Client Secret.

Procedure

1. Register your Developer Hub app in Azure, by using the Azure portal.

   1. Sign in to the Microsoft Entra admin center.
   2. 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.

   3. Browse to Applications > App registrations, and create a New registration with the configuration:

      Name

      Enter a name to identify your application in Azure, such as <Authenticating with Developer Hub>.

      Supported account types

      Select Accounts in this organizational directory only.

      Redirect URI

      Select a platform

      Select Web.

      URL

      Enter the backend authentication URI set in Developer Hub: https://<my_developer_hub_domain>/api/auth/microsoft/handler/frame

   4. On the Applications > App registrations > <Authenticating with Developer Hub> > Manage > API permissions page, Add a Permission, Microsoft Graph, select the following permissions:

      Application Permissions

      GroupMember.Read.All, User.Read.All

      Enter permissions that enable provisioning user and groups to the Developer Hub software catalog.

      Optional: Grant admin consent for these permissions. Even if your company does not require admin consent, consider doing so as it means users do not need to individually consent the first time they access Developer Hub.

      Delegated Permissions

      User.Read, email, offline_access, openid, profile

      Enter permissions that enable authenticating users.

      Optional: Enter optional custom scopes for the Microsoft Graph API that you define both here and in your app-config.yaml Developer Hub configuration file.

   5. On the Applications > App registrations > <Authenticating with Developer Hub> > Manage > Certificates & secrets page, in the Client secrets tab, create a New client secret.

   6. Save the following values for the next step:

      • Directory (tenant) ID
      • Application (client) ID
      • Application (client) Secret ID

2. Add your Azure credentials to Developer Hub, by adding the following key/value pairs to your Developer Hub secrets:

   MICROSOFT_TENANT_ID

   Enter your saved Directory (tenant) ID.

   MICROSOFT_CLIENT_ID

   Enter your saved Application (client) ID.

   MICROSOFT_CLIENT_SECRET

   Enter your saved Application (client) secret.

Procedure

1. Register the GitLab OAuth 2 application.

   Important

   You must use the required callback URL and permissions.

   1. Register a GitLab OAuth 2 application using the following configuration:

      GitLab OAuth 2 application name

      Enter a unique name, such as authenticating-with-rhdh-<GUID>.

      Redirect URI

      Enter your Developer Hub URL: https://<my_developer_hub_domain>.

      Authorization callback URL

      Enter your authentication backend URL: https://<my_developer_hub_domain>/api/auth/gitlab/handler/frame.

      Authorized application scope

      Enable email, profile, openid, and read_user.

   2. Save the application and record these values for the next step:
2. OAuth 2 Client ID, available in the Application ID field
3. OAuth 2 Client secret, accessible by selecting Copy in the Secret field
4. Set up a GitLab personal access token (PAT) with read_api scope. Save the token value for the next step.

5. Add your GitLab credentials to your RHDH secrets using the following key/value pairs. Use these environment variables in your RHDH configuration files.

   GITLAB_HOST

   Enter your GitLab host: <gitlab_host>.

   GITLAB_CLIENT_ID

   Enter the saved OAuth 2 Client ID.

   GITLAB_CLIENT_SECRET

   Enter the saved OAuth 2 Client Secret.

   GITLAB_TOKEN

   Enter the saved Personal access token.

   GITLAB_URL

   Enter the GitLab host domain: `<gitlab_host_domain>`.

   GITLAB_PARENT_ORG

   Enter your GitLab organization name, such as <your_gitlab_organization_name>.