Deploy IBM MQ developer patterns in a Backstage portal

Deploy the “IBM MQ resources for developers” component in Backstage to give your developers one place to find IBM MQ APIs, tutorials, learning paths, playlists, and starter samples.

Backstage is an open-source framework for building developer portals. You can use a developer portal to enforce standards, and to document and provide access to the approved resources, frameworks, tools, and APIs.

In this tutorial, you set up Backstage with persistent storage, import the “IBM MQ resources for developers” component, and then explore the IBM MQ developer resources in the Backstage catalog.

Prerequisites

To complete this tutorial, you 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, on macOS run xcode-select --install, or on Ubuntu install the make and build-essential packages.
Node.js Active long-term support (LTS) release. Node.js 22 or 24 is recommended. Install it by using nvm.
Yarn. Corepack is included with Node.js 22 and 24. Run corepack enable to activate it. The Backstage app that you create in Step 3 sets the Yarn version that it uses.
Podman or Docker
Git CLI
A GitHub account
An integrated development environment (IDE). For example, Visual Studio Code
Available ports 3000 and 7007
At least 20 GB of disk space and 6 GB of memory

The commands in this tutorial use podman. Depending on your environment, you can substitute docker or alias podman to docker.

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. Import IBM MQ resources for developers into Backstage
Step 6. Explore the imported IBM MQ resources component

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 for Backstage, you must import and add the catalog components again after each startup. For this reason, first create the persistent storage for Backstage to use.

Open a terminal window.
Run the following command to create a volume. In this example, the volume is named “postgredata.”
```
 podman volume create postgredata
```
Start the persistent storage by running the following command. Substitute a suitable user ID and password for and . These are 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 --name postgresql postgres
```
The volume is mounted at /var/lib/postgresql. Current versions of the Postgres image (version 18 and later) do not start if the volume is mounted at /var/lib/postgresql/data.
Confirm that the container is running.
```
 podman ps
```

Step 2. Create a GitHub token for Backstage

The IBM MQ resources for developers include templates that you can use to create sample GitHub repositories. Backstage needs a personal access token to create these repositories.

Open GitHub in a web browser.
Click your profile photo.
Select Settings.
On the left-hand menu, select Developer settings.
Select Personal access tokens > Tokens (classic).
Select Generate new token, and then select Generate new token (classic).

If you have never created a personal access token, you do not see the Revoke all button.
Give the token a name, an expiration, and the repo scope. In this example, the expiration is set to 30 days.
Click Generate token.
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.

In short, run the following command, enter a name for your app when prompted, and then change to the directory that is created for the app.

npx @backstage/create-app@latest

Step 4. Configure Backstage for persistence and GitHub

Open an IDE, and open the newly created Backstage app directory.
Create a file named app-config.local.yaml in the root of the app directory. This file overrides the configuration settings for Backstage, which are in the app-config.yaml file. Git excludes files that match *.local.yaml by default.

Enter the details of your persistent storage. Substitute <xxxx> with your Postgres user ID and <yyyy> with your Postgres password.

 backend:
   database:
     client: pg
     connection:
       host: localhost
       port: 5421
       user: <xxxx>
       password: <yyyy>

Below the backend section, add the integrations settings for GitHub. Replace yourtoken with the personal access token that you created earlier. Do not include any angle brackets around the token.
```
 integrations:
     github:
       - host: github.com
         token: yourtoken
```
Because you import templates and a group, update the Backstage catalog rules to allow Template and Group entities, as shown in the following example.
```
 catalog:
   rules:
     - allow: [Component, System, API, Resource, Location, Template, Group]
```

The app-config.local.yaml file should look like this when you are done (with your Postgres credentials and github token provided):

Completed `app-config.local.yaml` file

The GitHub scaffolder module (@backstage/plugin-scaffolder-backend-module-github) is already installed and enabled in a new Backstage app, so you do not need to install it or edit the /packages/backend/src/index.ts file.

Step 5. Import IBM MQ resources for developers into Backstage

Go back to your open terminal, and from the Backstage app directory, run yarn start.
Wait for the Rspack compiled successfully message. A browser window opens at http://localhost:3000. If it does not open, enter that address in a browser. Press Enter.
In the Backstage portal, in the navigation menu, select Create.
The only available template is the sample Node.js template that is included with Backstage. Click REGISTER EXISTING COMPONENT.
Enter the following URL: https://github.com/ibm-messaging/mq-dev-patterns/blob/master/backstage/catalog-info.yaml.
Click ANALYZE.
Review the summary of the entities to add to the Backstage catalog, and then click IMPORT.

Step 6. Explore the imported IBM MQ resources component

In this step, you explore some of the entities that are 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 are set up so that a developer can use the Backstage templates to create new repositories based on the IBM MQ developer resources component. The developer can then use the sample code to develop an application that is ready for deployment.

In the Backstage app, click Catalog. You see a new entry for the “IBM MQ resources for developers” component. If you do not see it, change the Personal filter from Owned to All.
Click the IBM MQ resources for developers link.

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

The Provided APIs section shows links to the IBM MQ APIs.
In the Backstage navigation menu, click Create to find the newly installed IBM MQ templates: MQ Node.js, MQ JMS, MQ Spring, MQ Python, MQ XMS dotnet, and MQ Go.
Click CHOOSE for any of the IBM MQ templates.
Enter a name. This name is the Backstage catalog entry name for the sample repository that is generated. Click NEXT.
Enter a repository name and an owner. The name is given to the new repository. It must not already exist in your GitHub account and must not contain spaces. The owner should correspond to your GitHub ID. Click NEXT.
Select the visibility for the new repository. Then, click REVIEW.
Review the new repository and component details, and then click CREATE.
Backstage creates the repository, which contains the sample code, and registers it as a component.
Click OPEN IN CATALOG.

The Relations section contains a reference to the IBM MQ API that is used in the sample.
Click VIEW SOURCE.

The newly created GitHub repository opens.
Go back to Backstage and click Catalog.

You 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 resources for developers” component. Your developers can use Backstage as a self-service portal and find the resources that they need to create and maintain messaging applications.

Products

Languages

Technologies

Events

External Resources

Champions