### Full Application Configuration with MCP Setup Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-configure-mcp-tokens-and-endpoints-to-authorize-client-access.adoc An example of a complete application configuration file including MCP token and endpoint settings, plugin sources, and OpenAI model configurations. ```yaml app: title: AI Dev {product-short} baseUrl: "${{product-very-short}_BASE_URL}" auth: environment: development session: secret: "${BACKEND_SECRET}" providers: guest: dangerouslyAllowOutsideDevelopment: true backend: actions: pluginSources: - software-catalog-mcp-extras - techdocs-mcp-extras - scaffolder-mcp-extras - catalog - scaffolder auth: externalAccess: - type: static options: token: ${MCP_TOKEN} subject: mcp-clients keys: - secret: "${BACKEND_SECRET}" baseUrl: "${{product-very-short}_BASE_URL}" cors: origin: "${{product-very-short}_BASE_URL}" signInPage: oidc ``` -------------------------------- ### Initialize Quick Start Modules in App.tsx Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-enable-guided-tutorials-to-learn-platform-features.adoc Import and include the quickstartInitModule and quickstartTranslationsModule in your Backstage application's createApp configuration to enable guided tutorials. This handles automatic first-visit display and notifications. ```typescript import { createApp } from '@backstage/frontend-defaults'; import { quickstartInitModule, quickstartTranslationsModule, } from '@red-hat-developer-hub/backstage-plugin-quickstart/alpha'; export default createApp({ features: [ quickstartInitModule, // Handles first-visit auto-open and notifications quickstartTranslationsModule, // Provides internationalization support // Additional features ], }); ``` -------------------------------- ### Example Extensions Configuration File Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-configure-rhdh-to-install-plugins-by-using-extensions.adoc Create a `dynamic-plugins.extensions.yaml` file to define plugins, including package paths, disabled status, and specific plugin configurations for frontend and backend extensions. This file specifies how to include localization resources, app icons, dynamic routes, and menu items for the marketplace plugin, and enables the installation of extensions by saving to a specified file path. ```yaml includes: - dynamic-plugins.default.yaml plugins: - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-extensions disabled: false pluginConfig: dynamicPlugins: frontend: red-hat-developer-hub.backstage-plugin-marketplace: translationResources: - importName: marketplaceTranslations ref: marketplaceTranslationRef module: Alpha appIcons: - name: pluginsIcon importName: PluginsIcon dynamicRoutes: - path: /extensions importName: DynamicMarketplacePluginRouter menuItem: icon: pluginsIcon text: Extensions textKey: menuItem.extensions menuItems: extensions: parent: default.admin - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-extensions-backend-dynamic disabled: false pluginConfig: extensions: installation: enabled: true saveToSingleFile: file: /opt/app-root/src/dynamic-plugins-root/dynamic-plugins.extensions.yaml ``` -------------------------------- ### Quick Start Application Configuration Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-customize-your-rhdh-quick-start.adoc Define quick start steps including title, description, icon, roles, and call-to-action for user onboarding. ```yaml app: quickstart: - title: 'Welcome to {product-short}' description: 'Learn the basics of navigating the {product-short} interface' icon: 'home' roles: ['admin', 'developer'] # Show to both roles cta: text: 'Get Started' link: '/catalog' - title: 'Create Your First Component' description: 'Follow our guide to register your first software component' icon: 'code' roles: ['admin', 'developer'] # Show to both roles cta: text: 'Create Component' link: '/catalog-import' - title: 'Explore Templates' description: 'Discover available software templates to bootstrap new projects' icon: 'template' roles: ['admin', 'developer'] # Show to both roles cta: text: 'Browse Templates' link: '/create' ``` -------------------------------- ### Install Custom Core Service as BackendFeature Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-override-core-backend-service-configuration.adoc Install your custom core service as a BackendFeature. This example demonstrates overriding the default HTTP router service. Ensure the corresponding environment variable (e.g., ENABLE_CORE_ROOTHTTPROUTER_OVERRIDE) is set to true to prevent the default implementation from being installed. ```javascript // Create the BackendFeature $ export const customRootHttpServerFactory: BackendFeature = rootHttpRouterServiceFactory({ configure: ({ app, routes, middleware, logger }) => { logger.info( 'Using custom root HttpRouterServiceFactory configure function', ); app.use(middleware.helmet()); app.use(middleware.cors()); app.use(middleware.compression()); app.use(middleware.logging()); // Add a the custom middleware function before all // of the route handlers app.use(addTestHeaderMiddleware({ logger })); app.use(routes); app.use(middleware.notFound()); app.use(middleware.error()); }, }); // Export the BackendFeature as the default entrypoint $ export default customRootHttpServerFactory; ``` -------------------------------- ### Install the Infrastructure Chart Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/extend_orchestrator-in-rhdh/proc-install-the-orchestrator-software-templates-infra-chart.adoc Use this command to install the orchestrator-software-templates-infra chart. Ensure you have cluster-admin privileges and the Helm CLI installed. ```bash $ helm install redhat-developer/redhat-developer-hub-orchestrator-infra ``` -------------------------------- ### Homepage Backend Configuration Example Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/ref-homepage-backend-configuration-reference.adoc Example of a complete homepage backend configuration with persona-based visibility rules for different user groups. ```yaml homepage: defaultWidgets: # Search bar - visible to all users - id: onboarding ref: 'rhdh-onboarding-section' layout: xl: { w: 12, h: 6 } lg: { w: 12, h: 6 } # Quick access card - visible to all users - id: quickaccess-card ref: quickaccess-card layout: xl: { w: 6, h: 8, x: 6 } # Group with shared visibility - visible only to admins - if: groups: [group:default/admins] children: - id: rbac ref: RBAC layout: xl: { w: 12, h: 6 } # Templates - visible only to developers - id: templates ref: TemplateSection if: groups: [group:default/developers] layout: xl: { w: 12, h: 5 } lg: { w: 12, h: 5 } ``` -------------------------------- ### Verify Infrastructure Chart Installation Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/extend_orchestrator-in-rhdh/proc-install-the-orchestrator-software-templates-infra-chart.adoc Run this command to verify that the redhat-developer-hub-orchestrator-infra chart has been successfully installed. ```bash $ helm test redhat-developer-hub-orchestrator-infra ``` -------------------------------- ### Example Request with Static Token using curl Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-enable-service-to-service-authentication-by-using-a-static-token.adoc Demonstrates how to make a GET request to the catalog locations API using `curl`, including the static token in the `Authorization` header for authentication. ```terminal $ curl --location --request GET '{my-product-url}/api/catalog/locations' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer __' ``` -------------------------------- ### Install Red Hat Developer Hub Helm Chart Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/install_installing-rhdh-on-ocp/proc-deploy-rhdh-on-ocp-with-the-helm-cli.adoc Installs the Red Hat Developer Hub Helm chart from a specified URL. Use this for an initial installation or to upgrade if no custom values are needed. ```bash helm upgrade redhat-developer-hub -i https://github.com/openshift-helm-charts/charts/releases/download/redhat-redhat-developer-hub-{product-chart-version}/redhat-developer-hub-{product-chart-version}.tgz ``` -------------------------------- ### Check Dynamic Plugins Installation Status Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/integrate_accelerating-ai-development-with-openshift-ai-connector-for-rhdh/ref-troubleshooting-connector-functionality.adoc Use this command to check the installation logs of the dynamic plugins within your {product-very-short} project Pod. This helps verify if the plugins have been successfully installed. ```bash $ oc logs -c install-dynamic-plugins deployment/ ``` -------------------------------- ### Install recommended packages for type checking Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-create-a-custom-transformer-to-provision-users-from-to-the-software-catalog.adoc Optionally install packages for `UserEntity` or `GroupEntity` type checking. ```shell $ yarn --cwd plugins/catalog-backend-module-msgraph-transformer add @backstage/catalog-model ``` -------------------------------- ### Run Installation Script (Disconnected Environment) Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/install_installing-rhdh-in-an-air-gapped-environment/proc-install-rhdh-in-a-fully-disconnected-environment-with-the-operator.adoc Execute the installation script within the disconnected environment to install the RHDH Operator. This script uses the images previously mirrored and transferred. If `oc mirror` was used for mirroring, it must also be used for installation. ```bash $ bash __/install.sh --from-dir __ [--to-registry __] [--use-oc-mirror true] ``` -------------------------------- ### Install dependencies, compile, and build plugins Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-example-of-installing-a-custom-plugin-in-rhdh.adoc Install project dependencies, compile TypeScript code, and build all plugins. This step prepares the plugin for export and packaging. ```terminal cd workspaces/entity-feedback yarn install yarn tsc yarn build:all ``` -------------------------------- ### Install recommended packages for default transformers Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-create-a-custom-transformer-to-provision-users-from-gitlab-to-the-software-catalog.adoc Optionally, install `@backstage/plugin-catalog-backend-module-gitlab` to extend default transformers or for Transformer type checking. ```shell $ yarn --cwd plugins/catalog-backend-module-gitlab-org-transformer add @backstage/plugin-catalog-backend-module-gitlab ``` -------------------------------- ### Inspect Plugin Installation Logs Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-verify-successful-installation-of-mcp-plugins.adoc Inspect the logs for the installation of the {product-very-short} dynamic plugins. This command retrieves logs from the specified deployment's install-dynamic-plugins container. ```bash $ oc logs -c install-dynamic-plugins deployment/ ``` -------------------------------- ### Synchronize Environment and Install Dependencies Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-configure-the-evaluation-environment-to-validate-model-accuracy.adoc Synchronize the environment and install all necessary dependencies using uv. This ensures all required packages are available for the evaluation. ```bash uv sync ``` -------------------------------- ### Example CSV Policies and Assignments Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-define-authorizations-in-external-files-by-using-the-operator.adoc This example demonstrates how to define permissions for guests and assign them to a user and a group using CSV format. ```csv p, role:default/guests, catalog-entity, read, allow p, role:default/guests, catalog.entity.create, create, allow g, user:default/my-user, role:default/guests g, group:default/my-group, role:default/guests ``` -------------------------------- ### Example pod log output Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/extend_orchestrator-in-rhdh/proc-deploy-workflows-on-a-cluster.adoc This is an example of output from pod logs, indicating a `ConfigurationException` due to a missing property. ```yaml SRCFG00040: The config property quarkus.openapi-generator.notifications.auth.BearerToken.bearer-token is defined as the empty String ("') which the following Converter considered to be null: io.smallrye.config.Converters$BuiltInConverter java.lang.RuntimeException: Failed to start quarkus ...Caused by: io.quarkus.runtime.configuration.ConfigurationException: Failed to read configuration properties ``` -------------------------------- ### Example Configuration with Custom Sidebar Item Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-define-dynamic-routes-for-new-plugin-pages.adoc This example demonstrates how to configure a dynamic route with a custom sidebar item component, passing specific props and specifying the import name for the sidebar item. ```yaml # dynamic-plugins-config.yaml plugins: - plugin: disabled: false pluginConfig: dynamicPlugins: frontend: my-dynamic-plugin-package-name: dynamicRoutes: - importName: CustomPage menuItem: config: props: text: Click Me! importName: SimpleSidebarItem path: /custom_page ``` -------------------------------- ### Example Loaded Plugins Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-install-dynamic-plugins-with-the-rhdh-operator.adoc This JSON output shows an example list of loaded dynamic plugins, including their names, versions, platforms, and roles, as retrieved from the /api/dynamic-plugins-info/loaded-plugins endpoint. ```json [ { "name": "backstage-plugin-catalog-backend-module-github-dynamic", "version": "0.5.2", "platform": "node", "role": "backend-plugin-module" }, { "name": "backstage-plugin-techdocs", "version": "1.10.0", "role": "frontend-plugin", "platform": "web" }, { "name": "backstage-plugin-techdocs-backend-dynamic", "version": "1.9.5", "platform": "node", "role": "backend-plugin" }, ] ``` -------------------------------- ### Example TechDocs Plugin Configuration for Helm Chart Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/assemblies/configure_techdocs-for-rhdh/assembly-configure-techdocs.adoc This is an example configuration for the TechDocs plugin when using the Helm chart. It shows how to set parameters related to storage and other plugin behaviors. ```yaml apiVersion: "helm.sh/v1" kind: "AppService" metadata: name: "{product-name}" spec: # ... other configurations techdocs: enabled: true # Example: Configure storage to use ODF storage: kind: "odf" odf: bucketName: "techdocs-storage" region: "us-east-1" # Example: Configure storage to use Amazon S3 # storage: # kind: "s3" # s3: # bucketName: "techdocs-storage" # region: "us-east-1" # endpoint: "s3.amazonaws.com" # credentials: # accessKeyId: "minioadmin" # secretAccessKey: "minioadmin" # Example: Configure storage to use a custom endpoint # storage: # kind: "s3" # s3: # bucketName: "techdocs-storage" # region: "us-east-1" # endpoint: "http://localhost:9000" # credentials: # accessKeyId: "minioadmin" # secretAccessKey: "minioadmin" # ... other configurations ``` -------------------------------- ### Add Quick Start Sidebar Button Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-enable-guided-tutorials-to-learn-platform-features.adoc Add a custom sidebar button to your navigation component that toggles the Quick Start drawer. This is necessary if the global header plugin is not installed. ```typescript import { useAppDrawer } from '@backstage/frontend-plugin-api'; import { WavingHandOutlinedIcon } from '@mui/icons-material'; import { QUICKSTART_DRAWER_ID } from '@red-hat-developer-hub/backstage-plugin-quickstart'; function QuickstartSidebarItem() { const { toggleDrawer } = useAppDrawer(); return ( toggleDrawer(QUICKSTART_DRAWER_ID)} /> ); } ``` -------------------------------- ### Integrate Simple Example Plugin with Frontend Configuration Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-add-a-dynamic-plugin-to-rhdh.adoc This example integrates a plugin named `simple-example` using an OCI image. It includes `pluginConfig` for frontend routing and mounting, specifying menu items and component configurations. ```yaml plugins: # Option 1: Load from an OCI image - package: oci://quay.io//simple-example:v0.1.0 disabled: false pluginConfig: dynamicPlugins: frontend: # The package name must match package.json (usually internal.backstage-plugin-) internal.backstage-plugin-simple-example: dynamicRoutes: - path: /simple-example # Must match the export in src/index.ts importName: SimpleExamplePage menuItem: icon: extension text: Simple Example mountPoints: - mountPoint: entity.page.overview/cards # Must match the export in src/index.ts importName: ExampleCard config: layout: gridColumnEnd: 'span 4' if: allOf: - isKind: component ``` -------------------------------- ### Disable Quick Start Plugin Configuration Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-disable-the-quick-start-plugin.adoc Set the 'disabled' property to 'true' within the plugin configuration to disable the quick start plugin. This prevents the guided onboarding steps from appearing. ```yaml global: dynamic: includes: - dynamic-plugins.default.yaml plugins: - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-quickstart disabled: true ``` -------------------------------- ### Example plugins.txt file format Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-mirror-plugins-from-a-file.adoc A text file listing the plugins to mirror, with each plugin URL on a new line. ```text oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-quay:1.8.0--1.22.1 oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-github-actions:1.8.0--0.11.1 oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-azure-devops:1.8.0--0.8.2 ``` -------------------------------- ### Run the Development Server Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-test-a-plugin-locally.adoc Start the local development server to test your plugin. This command boots up the Dev App with your configured changes. ```terminal $ yarn start ``` -------------------------------- ### Install logic-operator Subscription Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/extend_orchestrator-in-rhdh/proc-upgrade-the-openshift-serverless-logic-operator-for-rhdh-1-9.adoc This YAML configuration defines the necessary resources to install the `logic-operator` subscription in the `openshift-serverless-logic` namespace. It specifies the channel, approval strategy, catalog source, and the starting CSV version. ```yaml apiVersion: v1 kind: Namespace metadata: name: openshift-serverless-logic --- apiVersion: operators.coreos.com/v1 kind: OperatorGroup metadata: name: openshift-serverless-logic namespace: openshift-serverless-logic spec: --- apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: logic-operator namespace: openshift-serverless-logic spec: channel: stable # channel of an operator package to subscribe to installPlanApproval: Automatic # whether the update should be installed automatically name: logic-operator # name of the operator package source: redhat-operators # name of the catalog source sourceNamespace: openshift-marketplace startingCSV: logic-operator.v{rhoserverless-logic-version} # The initial version of the operator ``` -------------------------------- ### Example: Policy for Specific HTTP Methods Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/assemblies/shared/assembly-conditional-policies-reference.adoc This JSON defines a policy that applies only when the HTTP request method is GET. ```json { "name": "GetRequestPolicy", "description": "Applies only to GET requests.", "condition": { "operator": "EQUALS", "property": "request.method", "value": "GET" } } ``` -------------------------------- ### Run mirroring script Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-mirror-plugins-from-a-catalog-index-to-a-partially-disconnected-environment.adoc Execute the downloaded mirroring script with the plugin index and target registry. Replace `` with your actual registry URL. ```bash bash mirror-plugins.sh \ --plugin-index oci://quay.io/rhdh/plugin-catalog-index:{product-version} \ --to-registry __ ``` -------------------------------- ### Example: Policy for Specific HTTP Method and Path Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/assemblies/shared/assembly-conditional-policies-reference.adoc This JSON defines a policy that applies only when the HTTP request method is POST and the path starts with /api/v2/. ```json { "name": "PostToApiV2Policy", "description": "Applies to POST requests to /api/v2/.", "condition": { "operator": "AND", "operands": [ { "operator": "EQUALS", "property": "request.method", "value": "POST" }, { "operator": "STARTS_WITH", "property": "request.path", "value": "/api/v2/" } ] } } ``` -------------------------------- ### Configure dynamic routes and menu items Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-configure-a-dynamic-plugin-menu-item-for-your-rhdh-instance.adoc This example demonstrates configuring both dynamic routes and menu items within the `dynamicPlugins` section. It shows how to link a route path to a menu item and define parent menu configurations. ```yaml dynamicPlugins: frontend: __: dynamicRoutes: - path: ____ module: CustomModule importName: ____PluginPage menuItem: icon: # home | group | category | extension | school | __ text: ____ menuItems: my-plugin: priority: 10 parent: favorites favorites: icon: favorite title: Favorites priority: 100 ``` -------------------------------- ### Install Custom Header as a Dynamic Plugin Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-customize-your-rhdh-global-header.adoc Configure your custom header as a dynamic plugin by adding its reference to the `app-config-dynamic.yaml` file. This example shows how to specify mount points for application headers and other components. ```yaml - package: __ disabled: false pluginConfig: dynamicPlugins: frontend: : mountPoints: - mountPoint: application/header importName: __ config: position: above-main-content - mountPoint: global.header/component importName: __ config: priority: 100 - mountPoint: global.header/component importName: __ config: priority: 90 ``` -------------------------------- ### Example catalog-info.yaml file Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-register-components-manually-in-your-rhdh-instance.adoc Create this file in the root directory of your software project to define a component for registration. ```yaml apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: __ description: __ tags: - example - service annotations: github.com/project-slug: __ spec: type: __ owner: __ lifecycle: __ ``` -------------------------------- ### Basic Project Structure Example Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/extend_orchestrator-in-rhdh/con-project-structure-overview.adoc Illustrates the standard Quarkus project layout generated by the 'kn-workflow CLI'. Shows the typical directories and files, including 'pom.xml', 'README.md', and the 'src/main' directory with its subdirectories for Dockerfiles and resources. ```yaml 01_basic ├── pom.xml ├── README.md └── src └── main ├── docker │ ├── Dockerfile.jvm │ ├── Dockerfile.legacy-jar │ ├── Dockerfile.native │ └── Dockerfile.native-micro └── resources ├── application.properties ├── basic.svg ├── basic.sw.yaml ├── schemas │ ├── basic__main-schema.json │ └── workflow-output-schema.json └── secret.properties ``` -------------------------------- ### Retrieve Available Conditional Rules Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/assemblies/shared/assembly-conditional-policies-reference.adoc You can access API endpoints for conditional policies in {product}. For example, to retrieve the available conditional rules, which can help you define these policies, you can access the `GET [api/plugins/condition-rules]` endpoint. ```APIDOC ## GET api/plugins/condition-rules ### Description Retrieves a list of available conditional rules that can be used to define conditional policies. ### Method GET ### Endpoint /api/plugins/condition-rules ### Response #### Success Response (200) - **rules** (array) - A list of available conditional rules. #### Response Example { "rules": [ { "name": "example_rule_1", "description": "An example conditional rule." }, { "name": "example_rule_2", "description": "Another example conditional rule." } ] } ``` -------------------------------- ### Extensions Plugin Conditional Policy Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/ref-conditional-policy-plugin-examples.adoc This example restricts users in the 'role:default/extensions-admin' to only installing or updating a specific plugin identified by its name. The 'HAS_NAME' rule checks if the plugin name matches the one provided in the parameters. ```json { "result": "CONDITIONAL", "roleEntityRef": "role:default/extensions-admin", "pluginId": "extensions", "resourceType": "extensions-plugin", "permissionMapping": ["create"], "conditions": { "rule": "HAS_NAME", "resourceType": "extensions-plugin", "params": { "pluginNames": [""] } } } ``` -------------------------------- ### Configure Proxy with Overlapping PathRewrites Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-customize-the-learning-paths-by-using-a-hosted-json-file.adoc This example demonstrates how to configure the proxy when both Learning Paths and the homepage use overlapping `pathRewrites`. The Learning Paths configuration should precede the homepage configuration. ```yaml 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 ``` -------------------------------- ### Configure Quick Start Steps with Localization Keys Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-enable-quick-start-localization-in-rhdh.adoc Update your custom application configuration file to include translation keys for quick start titles, descriptions, and call-to-action texts. This ensures fallback to original text if localized strings are missing. ```yaml 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' # ... ``` -------------------------------- ### Define Localized Strings in Translation File Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-enable-quick-start-localization-in-rhdh.adoc Map the translation keys defined in your quick start configuration to their corresponding localized strings for each supported language in your translation file. This example shows English and French translations. ```yaml "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" } } ``` -------------------------------- ### Example JSON for QuickAccessCard Card Icons Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-customize-quickaccesscard-card-icons-on-the-rhdh-homepage.adoc This is an example of a JSON file structure used to configure the QuickAccessCard card on the homepage. It includes links with various icon types like external images, system icons, SVG strings, and relative paths. ```json [ { "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": "", "label": "Mailing List", "url": "https://groups.google.com/g/xyz" }, ] } ] ``` -------------------------------- ### View build script help menu Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/extend_orchestrator-in-rhdh/proc-build-workflow-images-locally.adoc Check the help menu of the build script to understand available options and usage. ```bash ./scripts/build.sh --help ``` -------------------------------- ### Install third-party plugin with Yarn Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-install-and-configure-a-third-party-techdocs-add-on.adoc Use this command to install the third-party plugin required for importing your TechDocs add-on. Ensure you have the `yarn` package manager installed. ```terminal $ yarn install ``` -------------------------------- ### Deploy {product-short} with Helm Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-deploy-on-eks-with-the-helm-chart.adoc Deploy {product-short} to your {eks-short} cluster using the Helm chart and the configured `values.yaml` file. ```terminal ``` -------------------------------- ### Verify MCP Backend Server Plugin Installation Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-verify-successful-installation-of-mcp-plugins.adoc Confirm the successful installation of the MCP backend server plugin. This log entry indicates that the plugin was successfully installed. ```text ..... prior logs .... ======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2 ==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:next__0.2.0 to local filesystem ==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2 ``` -------------------------------- ### Configure Jira Direct Setup in app-config.yaml Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/observability_evaluate-project-health-using-scorecards/proc-integrate-jira-health-metrics-using-scorecards.adoc Configure the Jira plugin for direct connection in your `{my-app-config-file}`. Ensure `JIRA_BASE_URL` and `JIRA_TOKEN` are set in your {product-very-short} secrets. ```yaml jira: baseUrl: ${JIRA_BASE_URL} token: ${JIRA_TOKEN} product: __ ``` -------------------------------- ### Install AKS Preview Azure CLI Extension Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-deploy-rhdh-on-with-the-helm-chart.adoc Install or upgrade the 'aks-preview' Azure CLI extension if it's not automatically installed. This extension is required for certain AKS features. ```bash $ az extension add --upgrade -n aks-preview --allow-preview true ``` -------------------------------- ### Create a plugin registry on OpenShift Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-create-a-tgz-file-with-dynamic-packages.adoc This snippet demonstrates how to set up an HTTP server for a plugin registry on OpenShift using `oc` commands. It involves creating a new build from an httpd image, starting the build from a local directory, and creating a new application. ```terminal $ oc project {my-product-namespace} $ oc new-build httpd --name=plugin-registry --binary $ oc start-build plugin-registry --from-dir=dynamic-plugins-root --wait $ oc new-app --image-stream=plugin-registry ``` -------------------------------- ### Verify MCP Tool Plugin Installation Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-verify-successful-installation-of-mcp-plugins.adoc Confirm the successful installation of an MCP tool plugin. This log entry indicates that a specific MCP tool plugin was successfully installed. ```text ..... prior logs .... ======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3 ==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3 to local filesystem ==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3 ``` -------------------------------- ### Initialize Backstage Application with Specific Version Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-create-a-new-application.adoc Initialize a new Backstage application in the current directory using a specific version of the `@backstage/create-app` package. Ensure the version matches the compatibility matrix for Red Hat Developer Hub. ```terminal $ npx @backstage/create-app@0.7.6 --path . ``` -------------------------------- ### Enter Plugin ID Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-create-a-new-plugin.adoc Provide a unique identifier for your new plugin. This example uses 'simple-example'. ```terminal ? What do you want to create? frontend-plugin - A new frontend plugin ? Enter the ID of the plugin [required] simple-example ``` -------------------------------- ### Install RHDH Helm Chart Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/install_installing-rhdh-in-an-air-gapped-environment/proc-install-rhdh-on-a-supported-kubernetes-platform-in-a-partially-disconnected-environment-with-the-helm-chart.adoc Install the Red Hat Developer Hub Helm chart using the `helm install` command. Ensure you have your `values.yaml` file configured and specify the Helm chart archive file name. ```bash $ helm install rhdh ./__ -f values.yaml ``` -------------------------------- ### Install required packages for the GitLab org transformer Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-create-a-custom-transformer-to-provision-users-from-gitlab-to-the-software-catalog.adoc Install the necessary `@backstage/plugin-catalog-backend-module-gitlab-org` package for your new module. ```shell $ yarn --cwd plugins/catalog-backend-module-gitlab-org-transformer add @backstage/plugin-catalog-backend-module-gitlab-org ``` -------------------------------- ### Dynamic Plugin Configuration Example Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/con-dynamic-front-end-plugins-for-application-use.adoc This YAML configuration demonstrates how to register a dynamic plugin and define its frontend wiring, including creating a new page and a corresponding sidebar menu item. Ensure the plugin path, package name, and import name are correctly specified. ```yaml # dynamic-plugins-config.yaml plugins: - plugin: ____ disabled: false pluginConfig: dynamicPlugins: my-plugin-package-name: # The plugin's unique package name dynamicRoutes: # Wiring for a new page/route - path: /my-new-page # The desired URL path importName: ____PluginPage # The exported component name menuItem: # Wiring for the sidebar entry icon: favorite # A registered icon name text: My Custom Page ``` -------------------------------- ### Select Plugin Type Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-create-a-new-plugin.adoc Choose the type of plugin you want to create from the interactive prompt. This example selects 'frontend-plugin'. ```terminal ? What do you want to create? (Use arrow keys) ❯ frontend-plugin - A new frontend plugin backend-plugin - A new backend plugin backend-plugin-module - A new backend module that extends an existing backend plugin plugin-web-library - A new web library plugin package plugin-node-library - A new Node.js library plugin package plugin-common-library - A new isomorphic common plugin package web-library - A library package, exporting shared functionality for web environments ``` -------------------------------- ### Install required packages for the transformer module Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-create-a-custom-transformer-to-provision-users-from-to-the-software-catalog.adoc Install the necessary package for the Microsoft Graph transformer module. ```shell $ yarn --cwd plugins/catalog-backend-module-msgraph-transformer add @backstage/plugin-catalog-backend-module-msgraph ``` -------------------------------- ### Install required packages for the GitHub org transformer Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-create-a-custom-transformer-to-provision-users-from-github-to-the-software-catalog.adoc Install the necessary @backstage/plugin-catalog-backend-module-github package for your custom transformer module. ```shell $ yarn --cwd plugins/catalog-backend-module-github-org-transformer add @backstage/plugin-catalog-backend-module-github-org ``` -------------------------------- ### QuickAccessCard Configuration Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-arrange-homepage-card-layouts-to-optimize-visual-organization.adoc Configure the QuickAccessCard for the Home page, defining its layout and optional title/path properties. ```yaml 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 ``` -------------------------------- ### Run mirroring script Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-mirror-plugins-from-a-file.adoc Execute the mirroring script using bash, providing the plugin list file and the target registry URL. ```terminal bash mirror-plugins.sh \ --plugin-list plugins.txt \ --to-registry __ ``` -------------------------------- ### Example: Base64 Encoding and Formatting Logo Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-customize-the-branding-logo-of-your-rhdh-instance.adoc Example demonstrating how to base64 encode an SVG logo and format it for the `BASE64_EMBEDDED_FULL_LOGO` variable. ```bash SVGLOGOBASE64=$(base64 -i logo.svg) BASE64_EMBEDDED_FULL_LOGO="data:image/svg+xml;base64,$SVGLOGOBASE64" ``` -------------------------------- ### Configure Proxy for Hosted JSON Learning Paths Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-customize-the-learning-paths-by-using-a-hosted-json-file.adoc Add this configuration to your {my-app-config-file} to enable the {product-short} proxy to access Learning Paths data from a hosted JSON file. Ensure the `pathRewrite` for learning paths is defined before the homepage configuration if both are used. ```yaml proxy: endpoints: '/developer-hub': target: __ pathRewrite: '^/api/proxy/developer-hub/learning-paths': '__' changeOrigin: true secure: true ``` -------------------------------- ### Workflow ID Evolution Example v1 Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/extend_orchestrator-in-rhdh/ref-unique-workflow-id-requirements-to-prevent-duplicates.adoc This example shows the initial definition of a workflow with a versioned ID and its associated version. ```yaml id: customer-onboarding-v1 version: "1.0" name: Customer Onboarding Workflow ``` -------------------------------- ### Install required packages for LDAP transformer Source: https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/blob/main/modules/shared/proc-create-a-custom-transformer-to-provision-users-from-ldap-to-the-software-catalog.adoc Install the necessary Backstage LDAP backend module package for your custom transformer plugin. ```shell $ yarn --cwd plugins/catalog-backend-module-ldap-transformer add @backstage/plugin-catalog-backend-module-ldap ```