Procedure

1. Create the Lightspeed Core Service (LCS) ConfigMap to store the service configuration:

   1. In the OpenShift Container Platform web console, navigate to your RHDH instance and select the ConfigMaps tab.

   2. Click Create ConfigMaps, select YAML view, and edit the file using the following structure. This example demonstrates the configuration for the LCS ConfigMap, typically named lightspeed-stack, which connects to the Llama Stack service locally on port 8321:

      kind: ConfigMap
      apiVersion: v1
      metadata:
        name: lightspeed-stack
      data:
        lightspeed-stack.yaml: |
          name: Lightspeed Core Service (LCS)
          service:
            host: 0.0.0.0
          # If the service does not run on port 8080, you must use ${env.LIGHTSPEED_SERVICE_PORT}. This value must match the port defined in lightspeed-app-config.yaml
          # port: ${env.LIGHTSPEED_SERVICE_PORT}
            auth_enabled: false
            workers: 1
            color_log: true
            access_log: true
          llama_stack:
            use_as_library_client: false
            url: http://localhost:8321
          user_data_collection:
            feedback_enabled: true
            feedback_storage: "/tmp/data/feedback"
            transcripts_enabled: true
            transcripts_storage: "/tmp/data/transcripts"
          authentication:
            module: "noop"
          conversation_cache:
            type: "sqlite"
            sqlite:
              db_path: "/tmp/data/conversations/lcs_cache.db"

      Important

      LCS requires Llama Stack expansion syntax for environment variables in the lightspeed-stack.yaml file. You must use the ${env.VAR} format with uppercase variable names. The service does not support lowercase names or omitting the env. prefix, such as ${env.var}.

   3. Click Create.

2. Create the Developer Lightspeed for RHDH ConfigMap (lightspeed-app-config) for plugin configurations:

   1. In the OpenShift Container Platform web console, navigate to your RHDH instance and select the ConfigMaps tab.

   2. Click Create ConfigMap, select YAML view, and add the following configuration:

      kind: ConfigMap
      apiVersion: v1
      metadata:
        name: lightspeed-app-config
        namespace: <__namespace__> # Enter your RHDH instance namespace
      data:
        app-config.yaml: |-
          backend:
            csp:
              upgrade-insecure-requests: false
            img-src:
              - "'self'"
              - "data:"
              - https://img.freepik.com
              - https://cdn.dribbble.com
              - https://avatars.githubusercontent.com # To load GitHub avatars
              - https://secure.gravatar.com           # To load Gravatar icons
              - https://<your_gitlab_url>            # To load GitLab icons
            script-src:
              - "'self'"
              - "'unsafe-eval'"
              - https://cdn.jsdelivr.net
      
          lightspeed:
            # OPTIONAL: Custom users prompts displayed to users
            # If not provided, the plugin uses built-in default prompts
            prompts:
              - title: Getting Started with Red Hat Developer Hub
                message: Can you guide me through the first steps to start using RHDH as a developer, like exploring the Software Catalog and adding my service?
      
            # OPTIONAL: Port for lightspeed service (default: 8080)
            # servicePort: ${LIGHTSPEED_SERVICE_PORT}
      
            # OPTIONAL: Override default RHDH system prompt
            # systemPrompt: "You are a helpful assistant focused on Red Hat Developer Hub development."

      Note

      To display user icons from external providers such as Gravatar or GitLab, include the provider URLs in the img-src directive of your Content Security Policy (CSP).

   3. Click Create.

3. Create Llama Stack Secret file (llama-stack-secrets) for LLM provider credentials:

   Important

   • Red Hat Developer Hub 1.9 supports vLLM, native OpenAI, Vertex AI, and Ollama providers. The vLLM provider uses the OpenAI API schema but it does not support the official OpenAI service (api.openai.com). To use official OpenAI credentials, you must use the native OpenAI provider instead of vLLM. Using OpenAI credentials with the vLLM provider causes errors or improper responses.
   1. In the OpenShift Container Platform web console, navigate to Secrets.

   2. Click Create → Key/value secret, select YAML view, and add the following structure:

      apiVersion: v1
      kind: Secret
      metadata:
        name: llama-stack-secrets
      type: Opaque
      stringData:
        ENABLE_VLLM: "true"
        ENABLE_VERTEX_AI: ""
        ENABLE_OPENAI: ""
        ENABLE_OLLAMA: ""
        VLLM_URL: "_<api_endpoint>_"
        VLLM_API_KEY: "_<api_key>_"
        VLLM_MAX_TOKENS: ""
        VLLM_TLS_VERIFY: ""
        OPENAI_API_KEY: ""
        VERTEX_AI_PROJECT: ""
        VERTEX_AI_LOCATION: ""
        GOOGLE_APPLICATION_CREDENTIALS: ""
        OLLAMA_URL: ""
        SAFETY_MODEL: "llama-guard3:8b"
        SAFETY_URL: "http://localhost:#####/v1"
        SAFETY_API_KEY: ""

      where:

      ENABLE_VLLM

      Enables the vLLM provider. Set to true to activate.

      ENABLE_OPENAI

      Enables the OpenAI provider. Set to true to activate.

      ENABLE_VERTEX_AI

      Enables the Vertex AI provider. Set to true to activate.

      ENABLE_OLLAMA

      Enables the Ollama provider. Set to true to activate.

      Note

      To disable a provider, leave the value blank. (for example: ENABLE_VLLM="")

      VLLM_URL

      The API endpoint URL for the LLM provider. The provider must comply with the OpenAI API specification. Examples include OpenAI, Red Hat OpenShift AI, and vLLM.

      VLLM_API_KEY

      Required for remote services: Set this to the API key or token required for authentication with your remote LLM provider, if it is compatible with the OpenAI API specification.

      VLLM_MAX_TOKENS

      Optional. The maximum number of tokens the model generates.

      VLLM_TLS_VERIFY

      Optional. Specifies whether the system verifies the TLS certificate for the vLLM endpoint.

      OPENAI_API_KEY

      The API key required to access OpenAI models through the OpenAI API.

      VERTEX_AI_PROJECT

      The Google Cloud project ID required to access Gemini through Vertex AI.

      VERTEX_AI_LOCATION

      The Google Cloud region required to access Gemini through Vertex AI.

      GOOGLE_APPLICATION_CREDENTIALS

      The credentials required to authenticate with Google Cloud to access Vertex AI.

      OLLAMA_URL

      The URL for the Ollama service.

      SAFETY_MODEL

      The identifier for the safety model. The default model is llama-guard3:8b, which is optimized by Llama Stack for safety classification.

      SAFETY_URL

      The URL hosting the safety model. You must append /v1 to the host address (for example: localhost:#/v1) so the Llama Stack can correctly route moderation requests to the API.

      SAFETY_API_KEY

      The authentication token from your safety model required to secure the moderation channel and prevent unauthorized access to your safety infrastructure.

      Tip

      To integrate Developer Lightspeed for RHDH effectively with Model Context Protocol (MCP), you must provide the correct authorization headers. For details instructions, see {model-context-protocol-link}#proc-configuring-mpc-clients-to-access-the-rhdh-server_assembly-model-context-protocol-tools[Configuring MCP clients to access the RHDH server].

   3. Click Create.

4. Update the dynamic plugins ConfigMap: Add the Developer Lightspeed for RHDH plugin image to your existing dynamic plugins ConfigMap (dynamic-plugins-rhdh).

   includes:
   - dynamic-plugins.default.yaml
   plugins:
   - disabled: false
     package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed:bs_1.45.3__1.2.3
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-lightspeed:
                 translationResources:
                   - importName: lightspeedTranslations
                     module: Alpha
                     ref: lightspeedTranslationRef
                 dynamicRoutes:
                   - path: /lightspeed
                     importName: LightspeedPage
                 mountPoints:
                   - mountPoint: application/listener
                     importName: LightspeedFAB
                   - mountPoint: application/provider
                     importName: LightspeedDrawerProvider
                   - mountPoint: application/internal/drawer-state
                     importName: LightspeedDrawerStateExposer
                     config:
                       id: lightspeed
                   - mountPoint: application/internal/drawer-content
                     importName: LightspeedChatContainer
                     config:
                       id: lightspeed
                       priority: 100
   - disabled: false
     package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed-backend:bs_1.45.3__1.2.3

5. Required only if your environment uses another global floating action button (FAB): You must move the existing FAB or disable it to prevent interface elements from overlapping by updating your dynamic plugin configuration file with the following changes:

   - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-bulk-import
     disabled: true
     pluginConfig:
       dynamicPlugins:
         frontend:
           red-hat-developer-hub.backstage-plugin-bulk-import:
             mountPoints:
             # START: If the user has an existing BulkImportPage FAB, move the FAB to the left
               - mountPoint: global.floatingactionbutton/config
                 importName: BulkImportPage
                 config:
                   slot: 'bottom-left'
             # END
                   icon: BulkImportIcon
                   label: 'Bulk import'
                   toolTip: 'Register multiple repositories in bulk'
                   to: /bulk-import
             translationResources:
             - importName: bulkImportTranslations
               module: Alpha
               ref: bulkImportTranslationRef
             appIcons:
             - name: bulkImportIcon
               importName: BulkImportIcon
             dynamicRoutes:
             - path: /bulk-import
               importName: BulkImportPage
               menuItem:
                 icon: bulkImportIcon
                 text: Bulk import
                 textKey: menuItem.bulkImport

6. Update your deployment configuration: Update the deployment configuration based on how your RHDH instance was installed. You must add two sidecar containers: llama-stack and lightspeed-core.

   • For an Operator-installed RHDH instance (Update Backstage custom resource (CR)):

     1. In the spec.application.appConfig.configMaps section of your Backstage CR, add the Developer Lightspeed for RHDH custom app configuration:

        appConfig:
          configMaps:
            - name: lightspeed-app-config

     2. Update the spec.deployment.patch.spec.template.spec.volumes specification to include volumes for LCS configuration (lightspeed-stack), shared storage for feedback (shared-storage), and RAG data (rag-data-volume):

        volumes:
          - configMap:
              name: lightspeed-stack
            name: lightspeed-stack
          - emptyDir: {}
            name: shared-storage
          - emptyDir: {}
            name: rag-data-volume

     3. Update the spec.deployment.patch.spec.template.spec.initContainers specification section to initialize RAG data:

        initContainers:
          - name: init-rag-data
            image: 'quay.io/redhat-ai-dev/rag-content:release-1.9-lcs'
            command: ["sh", "-c", "cp -r /rag/vector_db/rhdh_product_docs /rag-content/ && cp -r /rag/embeddings_model /rag-content/"]
            volumeMounts:
              - mountPath: /rag-content
                name: rag-data-volume

     4. Add the Llama Stack (llama-stack) and the LCS (lightspeed-core) containers to the spec.deployment.patch.spec.template.spec.containers section:

        containers:
          # ... Your existing RHDH container definition ...
          - envFrom:
              - secretRef:
                  name: llama-stack-secrets
            image: 'quay.io/redhat-ai-dev/llama-stack:0.1.4' # Llama Stack image
            name: llama-stack
            volumeMounts:
              - mountPath: /app-root/.llama
                name: shared-storage
              - mountPath: /rag-content
                name: rag-data-volume
          - image: 'quay.io/lightspeed-core/lightspeed-stack:0.4.0' # Lightspeed Core Service image
            name: lightspeed-core
            volumeMounts:
              - mountPath: /app-root/lightspeed-stack.yaml
                name: lightspeed-stack
                subPath: lightspeed-stack.yaml
              - mountPath: /tmp/data/feedback
                name: shared-storage
              - mountPath: /tmp/data/transcripts
                name: shared-storage
              - mountPath: /tmp/data/conversations
                name: shared-storage

     5. Click Save. The Pods are automatically restarted.

   • For a Helm-installed RHDH instance (Update the Helm chart):

     1. Add your dynamic plugins configuration in the global.dynamic property.

        global:
          dynamic:
            plugins:
              - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed:bs_1.45.3__1.2.3
                pluginConfig:
                  dynamicPlugins:
                    frontend:
                      red-hat-developer-hub.backstage-plugin-lightspeed:
                        translationResources:
                          - importName: lightspeedTranslations
                            module: Alpha
                            ref: lightspeedTranslationRef
                        dynamicRoutes:
                          - path: /lightspeed
                            importName: LightspeedPage
                        mountPoints:
                          - mountPoint: application/listener
                            importName: LightspeedFAB
                          - mountPoint: application/provider
                            importName: LightspeedDrawerProvider
                          - mountPoint: application/internal/drawer-state
                            importName: LightspeedDrawerStateExposer
                            config:
                              id: lightspeed
                          - mountPoint: application/internal/drawer-content
                            importName: LightspeedChatContainer
                            config:
                              id: lightspeed
                              priority: 100
              - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed-backend:bs_1.45.3__1.2.3

     2. Add your Developer Lightspeed for RHDH custom app config file to extraAppConfig:

            extraAppConfig:
              - configMapRef: lightspeed-app-config
                filename: app-config.yaml

     3. Add the Llama Stack Secret file to extraEnvVarsSecrets:

            extraEnvVarsSecrets:
              - llama-stack-secrets

     4. Update the extraVolumes section to include the LCS ConfigMap (lightspeed-stack), shared storage, and RAG data volume:

            extraVolumes:
              - configMap:
                  name: lightspeed-stack
                name: lightspeed-stack
              - emptyDir: {}
                name: shared-storage
              - emptyDir: {}
                name: rag-data-volume

     5. Update the upstream.backstage.initContainers section (if supported by your Helm chart structure) to initialize RAG data.

          initContainers:
              - name: init-rag-data
                image: 'quay.io/redhat-ai-dev/rag-content:release-1.9-lcs'
                command:
                  - "sh"
                  - "-c"
                  - "echo 'Copying RAG data...'; cp -r /rag/vector_db/rhdh_product_docs /data/ && cp -r /rag/embeddings_model /data/ && echo 'Copy complete.'"
                volumeMounts:
                  - mountPath: /data
                    name: rag-data-volume

     6. Add the Llama Stack and LCS container definitions to extraContainers.

        Note

        If you have Road-Core Service installed from the previous Red Hat Developer Lightspeed for Red Hat Developer Hub configuration, you must replace the older single container configuration found in source with the two sidecars.

            extraContainers:
              # Llama Stack Container
              - envFrom:
                  - secretRef:
                      name: llama-stack-secrets
                image: 'quay.io/redhat-ai-dev/llama-stack:0.1.4'
                name: llama-stack
                volumeMounts:
                  - mountPath: /app-root/.llama
                    name: shared-storage
                  - mountPath: /rag-content/embeddings_model
                    name: rag-data-volume
                    subPath: embeddings_model
                  - mountPath: /rag-content/vector_db/rhdh_product_docs
                    name: rag-data-volume
                    subPath: rhdh_product_docs
              # Lightspeed Core Service Container
              - image: 'quay.io/lightspeed-core/lightspeed-stack:0.4.0'
                name: lightspeed-core
                volumeMounts:
                  - mountPath: /app-root/lightspeed-stack.yaml
                    name: lightspeed-stack
                    subPath: lightspeed-stack.yaml
                  - mountPath: /tmp/data/feedback
                    name: shared-storage
                  - mountPath: /tmp/data/transcripts
                    name: shared-storage
                  - mountPath: /tmp/data/conversations
                    name: shared-storage

     7. Click Save and then Helm upgrade.

7. Optional: Manage authorization (RBAC): If you have users who are not administrators, you must define permissions and roles for them to use Developer Lightspeed for RHDH. The Lightspeed Backend plugin uses Backstage RBAC for authorization.

   • For an Operator-installed RHDH instance:

     1. Configure the required RBAC permission by defining an rbac-policies.csv file, including lightspeed.chat.read, lightspeed.chat.create, and lightspeed.chat.delete permissions:

        p, role:default/_<your_team>_, lightspeed.chat.read, read, allow
        p, role:default/_<your_team>_, lightspeed.chat.create, create, allow
        p, role:default/_<your_team>_, lightspeed.chat.delete, delete, allow
        g, user:default/_<your_user>_, role:default/_<your_team>_

     2. Upload your rbac-policies.csv file to an rbac-policies ConfigMap in your OpenShift Container Platform project containing RHDH and update your Backstage CR:

        apiVersion: rhdh.redhat.com/v1alpha5
        kind: Backstage
        spec:
          application:
            extraFiles:
              mountPath: /opt/app-root/src
              configMaps:
                - name: rbac-policies

   • For a Helm-installed RHDH instance:

     1. Configure the required RBAC permission by defining an rbac-policies.csv file:

        p, role:default/_<your_team>_, lightspeed.chat.read, read, allow
        p, role:default/_<your_team>_, lightspeed.chat.create, create, allow
        p, role:default/_<your_team>_, lightspeed.chat.delete, delete, allow
        g, user:default/_<your_user>_, role:default/_<your_team>_

     2. Optional: Declare policy administrators by editing your custom RHDH ConfigMap (app-config.yaml) and adding the following code to enable selected authenticated users to configure RBAC policies through the REST API or Web UI:

          permission:
            enabled: true
            rbac:
              policies-csv-file: /opt/app-root/src/rbac-policies.csv
              policyFileReload: true
            admin:
              users:
                - name: user:default/<your_policy_administrator_name>

Verification

1. Log in to your RHDH instance.
2. Verify that you can see and access the Lightspeed FAB in the home page.
3. Select the Lightspeed FAB and verify the chat screen loads.