Procedure

1. In the navigation menu of the OpenShift Container Platform console, click Operators > OperatorHub.
2. In the Filter by keyword box, enter Developer Hub and click the Red Hat Developer Hub Operator card.
3. On the Red Hat Developer Hub Operator page, read the information about the Operator and click Install to open the Install Operator page.

4. After the Operator is successfully installed, provision your custom configuration:

   Before you create a Developer Hub instance, you must create the required config map and Secret resources in your project. These include the baseUrl and service-to-service authentication secrets.

   For detailed steps, see Provisioning your custom Red Hat Developer Hub configuration.

5. From the Update channel drop-down menu, select the update channel that you want to use, for example, fast or fast-1.7.

   Important

   The `fast channel includes all of the updates available for a particular version. Any update might introduce unexpected changes in your Red Hat Developer Hub deployment. Check the release notes for details about any potentially breaking changes.

   The fast-1.7 channel only provides z-stream updates, for example, updating from version 1.7.1 to 1.7.2. If you want to update the Red Hat Developer Hub y-version in the future, for example, updating from 1.7 to 1.7, you must switch to the fast-1.7 channel manually.

6. From the Version drop-down menu, select the version of the Red Hat Developer Hub Operator that you want to install. The default version is the latest version available in the selected channel.

7. Select the Operator Installation mode.

   Note

   The All namespaces on the cluster (default) option is selected by default. The Specific namespace on the cluster option is not currently supported.

8. In the Installed Namespace field, do one of the following actions:

   • Select Operator recommended Namespace to create and use the rhdh-operator namespace. This option is selected by default.

   • Select Select a Namespace to use an alternative namespace.

     • From the Select Project drop-down menu, do one of the following actions:

       • Select an existing project.

       • Select Create Project to create a new project for the Operator.

         • On the Create Project dialog, enter text into the required fields and click Create.

           Important

           For enhanced security, better control over the Operator lifecycle, and preventing potential privilege escalation, install the Red Hat Developer Hub Operator in a dedicated default rhdh-operator namespace. You can restrict other users' access to the Operator resources through role bindings or cluster role bindings.

           You can also install the Operator in another namespace by creating the necessary resources, such as an Operator group. For more information, see Installing global Operators in custom namespaces.

           However, if the Red Hat Developer Hub Operator shares a namespace with other Operators, then it shares the same update policy as well, preventing the customization of the update policy. For example, if one Operator is set to manual updates, the Red Hat Developer Hub Operator update policy is also set to manual. For more information, see Colocation of Operators in a namespace.

9. Select the Update approval method for the Operator.

   • If you select the Automatic option, the Operator is updated without requiring manual confirmation.
   • If you select the Manual option, a notification opens when a new update is released in the update channel. The update must be manually approved by an administrator before installation can begin.

10. Click Install.

    Note

    If you selected a Manual approval strategy, the upgrade status of the subscription remains Upgrading until you review and approve the install plan. After you click Approve on the Install Plan page, the subscription upgrade status changes to Up to date.

    If you selected an Automatic approval strategy, the upgrade status should resolve to Up to date without intervention.

Procedure

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

   1. Enter your custom logo.

      BASE64_EMBEDDED_FULL_LOGO="data:image/svg+xml;base64,<base64_full_logo_data>"
      BASE64_EMBEDDED_ICON_LOGO="data:image/svg+xml;base64,<base64_icon_logo_data>"

      BASE64_EMBEDDED_FULL_LOGO

      Enter your logo for the expanded (pinned) sidebar as a base64 encoded SVG image.

      To encode your logo in base64, run:

      $ base64 -i logo.svg

      BASE64_EMBEDDED_ICON_LOGO

      Enter your logo for the collapsed (unpinned) sidebar as a base64 encoded SVG image.

   2. Enter the connection string to your Redis server that caches plugin assets.

      REDIS_CONNECTION=rediss://user:pass@cache.example.com:6379

   3. Enter your GitHub integration credentials:

      GITHUB_INTEGRATION_APP_ID=_<Enter_the_saved_App_ID>
      GITHUB_INTEGRATION_CLIENT_ID=<Enter_the_saved_Client_ID>
      GITHUB_INTEGRATION_CLIENT_SECRET=<Enter_the_saved_Client_Secret>
      GITHUB_INTEGRATION_HOST_DOMAIN=github.com
      GITHUB_INTEGRATION_ORGANIZATION=<Enter_your_github_organization_name>
      GITHUB_INTEGRATION_PRIVATE_KEY_FILE= <Enter_the_saved_Private_key>

   4. Enter your PosgreSQL database secrets:

      POSTGRES_PASSWORD: <postgres-password>
      POSTGRES_PORT: "<postgres-port>"
      POSTGRES_USER: <postgres-username>
      POSTGRES_HOST: <postgres-host>
      PGSSLMODE: verify-full
      NODE_EXTRA_CA_CERTS: /opt/app-root/src/postgres-crt.pem

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

   1. For a production environment start with:

      app-config.yaml

      app:
        title: <Red Hat Developer Hub>
        branding:
          fullLogo: ${BASE64_EMBEDDED_FULL_LOGO}
          fullLogoWidth: 110px
          iconLogo: ${BASE64_EMBEDDED_ICON_LOGO}
      backend:
        cache:
          store: redis
          connection: ${REDIS_CONNECTION}
      techdocs:
        cache:
          ttl: 3600000
      catalog:
        providers:
          github:
            providerId:
              organization: "${GITHUB_INTEGRATION_ORGANIZATION}"
              schedule:
                frequency:
                  minutes: 30
                initialDelay:
                  seconds: 15
                timeout:
                  minutes: 15
      integrations:
        github:
          - host: ${GITHUB_INTEGRATION_HOST_DOMAIN}
            apps:
              - appId: ${GITHUB_INTEGRATION_APP_ID}
                clientId: ${GITHUB_INTEGRATION_CLIENT_ID}
                clientSecret: ${GITHUB_INTEGRATION_CLIENT_SECRET}
                privateKey: |
                  ${GITHUB_INTEGRATION_PRIVATE_KEY_FILE}
      permission:
        enabled: true
        rbac:
          admin:
            users:
              - name: user:default/<your_policy_administrator_name>
          pluginsWithPermission:
            - catalog
            - scaffolder
            - permission

      Most fields use environment variables that you defined in secrets in the previous step.

      app

      title

      Enter your Developer Hub instance display name, such as <Red Hat Developer Hub>.

      branding

      Set your custom logo.

      Optionally, customize the width of the branding logo by changing value for the fullLogoWidth field. The following units are supported: integer, px, em, rem, percentage.

      backend

      cache

      Enable the plugins assets cache.

      techdocs

      cache

      Enable the Techdocs cache.

      catalog

      provider

      github

      Enable GitHub repository discovery.

      integrations

      github

      Enable GitHub repository discovery.

      permissions

      Enable Role-based access control. Enter your policy administrator name.

   2. Additionally, provision users and enabling authentication with your external identity provider.

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

      Alternatively, create the project by using the web console.

   2. Provision your app-config.yaml and dynamic-plugins.yaml files respectively to the my-rhdh-app-config and dynamic-plugins-rhdh config maps 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

      Alternatively, 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

      Alternatively, create the secret by using the web console.

   4. Provision your PosgreSQL TLS certificates to the my-rhdh-database-secrets secret in the <my-rhdh-project> project.

      $ oc create secret generic my-rhdh-secrets --from-file=postgres-ca.pem --from-file=postgres-crt.pem --from-file=postgres-key.key --namespace=my-rhdh-project

Procedure

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

   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/v1alpha3
   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:
         envs:
           - name: HTTP_PROXY
             value: 'http://10.10.10.105:3128'
           - name: HTTPS_PROXY
             value: 'http://10.10.10.106:3128'
           - name: NO_PROXY
             value: 'localhost,example.org'
         secrets:
            - name: my-rhdh-secrets
       extraFiles:
         mountPath: /opt/app-root/src
         secrets:
           - name: my-rhdh-database-certificates-secrets
             key: postgres-crt.pem, postgres-ca.pem, postgres-key.key
       replicas: 2
     database:
       enableLocalDb: false

   application

   appConfig

   Register your my-rhdh-app-config and rbac-policies config maps.

   dynamicPluginsConfigMapName

   Register your dynamic-plugins-rhdh config map.

   extraEnvs

   env

   Enter your proxy environment variables.

   secrets

   Register your <my_product_secrets> and my-rhdh-database-secrets secrets.

   extraFiles

   secrets

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

   replicas

   Enable high availability (HA) by increasing the replicas count to a value higher or equal to 2.

   database

   enableLocalDb

   Use your external PostgreSQL database rather than the internal PostgreSQL database.

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. From the Developer Hub web console, click Settings.

2. From the Appearance panel, click LIGHT THEME, DARK THEME, or AUTO to change the theme mode.