Deploy and explore IBM MQ developer patterns in Backstage

Backstage is an open-source framework that allows developers to build developer portals for developers. A developer portal can be used to enforce standards, limit, document and provide access to the resources, frameworks, tools and APIS that have been approved for use.

In this tutorial you will deploy and explore the “IBM MQ resources for developers” component for Backstage. This puts IBM MQ APIs, tutorials, learning paths, playlists, and starter samples right where your developers hang-out.

If you are new to Backstage you will set up Backstage with persistent storage, import the “IBM MQ resources for developers” component, and then get hands-on with the IBM MQ developer resources in the Backstage ecosystem.

Prerequisites

To complete this tutorial, you will need the following Backstage prerequisites

• Access to a Unix-based operating system, such as Linux, MacOS or Windows subsystem for Linux
• A GNU-like build environment available at the command line. For example, XCode for MacOS, Or the make and build-essential packages for Ubuntu.
• Node.js. We recommended that you install it by using nvm
• yarn
• Podman or Docker
• Git CLI
• A Github account
• An IDE. For example, VSCode

In this tutorial we illustrate podman commands, but these can be substituted with docker or aliased with docker depending on your environment.

Steps

This tutorial consists of the following steps:

• Step 1. Set up persistent storage for Backstage
• Step 2. Create a github token for Backstage
• Step 3. Install the Backstage standalone app
• Step 4. Configure Backstage for persistence and github
• Step 5. Start Backstage, and import IBM MQ resources for developers
• Step 6. Explore the imported IBM MQ resources for developers

If you already have Backstage, you can skip to Step 5. However, you might need to go through steps 2 and 4 to configure Backstage for persistence and for Github.

Step 1. Set up persistent storage for Backstage

If you do not have persistent storage components for Backstage, you will have to import and add them to Backstage after each startup. For this reason, we will first create the persistent storage for Backstage to use.

1. Open a terminal window.

2. Run the following command to create a volume. In our example, we name the volume “postgredata.”

    podman volume create postgredata
   

3. Start up the persistent storage by running the command, remembering to substitute a suitable user ID and password for and , that will be used as the new credentials for this postgres database.

    podman run -itd -e POSTGRES_USER=<xxxx> -e POSTGRES_PASSWORD=<yyyy> -p 5421:5432 -v postgredata:/var/lib/postgresql/data --name postgresql postgres
   

Step 2. Create a GitHub token for Backstage

The IBM MQ resources for developers, includes templates from which new custom sample GitHub repositories can be created. Backstage needs a personal access token to create these repositories.

1. Open up GitHub in a web browser.
2. Click on your photo.
3. Select Settings.
4. On the left-hand menu, select Developer settings.
5. Select Personal access tokens > Tokens.

6. Select Generate new token

   

   If you have never created a Personal access token, then you won’t see the Revoke all button.

7. Give the token a name, an expiration, and suitable repo access. In this example, we have set the expiration to 30 days.

   

8. Click Generate token.

9. Copy the token to the clipboard.

Step 3. Install the Backstage standalone app

Install the Backstage app by following the instructions available in the Backstage docs

Step 4. Configure Backstage for persistence and github

1. Open an IDE, and open the newly created backstage app directory.

2. Open the app-config.local.yaml file. This file overrides the configuration settings for Backstage, which can be found in the app-config.yaml file.

   

3. Enter the details of your persistent storage remembering to substitute for your postgres user id and for your postgres password.

   

4. Below ‘backend’, add the ‘integration’ settings for github, remembering to enter the personal access token you created earlier.

   

5. Because you will be importing new templates, update the Backstage catalog rules to allow new template additions.

   

6. Now go back to your terminal window and run following the command to install the Backstage backend integration scaffold for GitHub.

    yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend-module-github
   

7. Go back to your IDE and open the /packages/backend/src/index.ts file.

   

8. Enable the GitHub integration by adding the following code before the backend.start(); line:

    backend.add(import('@backstage/plugin-scaffolder-backend-module-github'));
   

   

Step 5. Import IBM MQ resources for developers into Backstage

1. Go back to your open terminal, and from the backstage app directory, run yarn dev.

2. This will open a browser window. Click ENTER.

   

3. In the Backstage portal, in the left nav menu, select Home. On the Home page, click CREATE.

   

4. The only available template is an out of the box, hello world Node.js sample. Click REGISTER EXISTING COMPONENT.

   

5. Enter the following URL: https://github.com/ibm-messaging/mq-dev-patterns/blob/master/backstage/catalog-info.yaml.

6. Click ANALYZE.

   

7. Review the summary of the entities that will be added to the backstage catalog, and then click IMPORT.

   

Step 6. Explore the imported MQ resources component

In this step, you will explore some of the entities that were installed as part of the “IBM MQ resources for developers” component for Backstage, which includes the IBM MQ sample code templates. The IBM MQ developer resources on GitHub have been instrumented so that a developer can use the Backstage templates to base new repositories on the IBM MQ developer resources component and use the sample code to develop a new application ready for deployment.

1. In the backstage app, click Home. You will now see a new entry for the “IBM MQ resources for developers” component.

   

2. Click the IBM MQ resources for developers’ link.

   The Links section shows a curated list of IBM MQ Developer related playlists, learning paths, APIs, and samples.

   

   The Relations section shows clickable links to the IBM MQ APIs.

   

3. On the Left hand side Backstage menu click on Create… to find the newly installed IBM MQ templates.

   

4. Click CHOOSE for any of the IBM MQ templates.

   

5. Enter a name. This will be the Backstage catalog entry name for the sample repository that will be generated. Click NEXT.

   

6. Enter a repository name and an owner. The name will be given to the newly generated repository. The owner should correspond to your GitHub ID. Click NEXT.

   

7. Select visibility for the new repository. Then, click REVIEW.

   

8. Review the new repository and component details, and then click CREATE.

   

9. The repository will be created, containing the sample code, and registered as a component in Backstage.

   

10. Click OPEN IN CATALOG.

    The Relations section will now contain a clickable reference to the IBM MQ API that is used in the sample.

    

11. Click VIEW SOURCE.

    

    This will open the newly created GitHub repository.

    

12. Go back to Backstage and click Home.

    

    You will see a new entry for your repository in the list of backstage components.

Summary

In this tutorial, you created and configured a standalone instance of Backstage and imported the IBM MQ for developers’ component. Your developers can use Backstage as a self-service portal and find the resources that they will need on their journey as they create and maintain messaging applications.