Developer

Portals
Prepare to Perform with Red Hat Developer Hub

Preview
edition

Joshua Wood, Hans-Peter Grahsl, and Ryan Jarvinen

Developer Portals
Prepare to Perform with Red Hat Developer Hub

by Joshua Wood, Hans-Peter Grahsl, and Ryan Jarvinen

This preview edition of Developer Portals, Chapters

1, 5, and 6, is a work in progress. The final book is
estimated to be released in early 2024.
Table of Contents
Chapter 1: A platform for portals...........................................................................................................................1
The proliferating complexity of simple applications......................................................................................1
Hello [cruel] World........................................................................................................................................2
Internal developer platforms............................................................................................................................2
Backstage: A platform for building developer portals.................................................................................3
Backstage history.........................................................................................................................................3
Backstage today: Project and ecosystem................................................................................................4
Red Hat Developer Hub..............................................................................................................................4
Summary............................................................................................................................................................5
Chapter 5: Templates: Application head start....................................................................................................6
The Point of Interest Map application.............................................................................................................6
Application specifics.........................................................................................................................................7
Structure and technologies........................................................................................................................7
Architecture..................................................................................................................................................7
Software templates...........................................................................................................................................8
Template structure.......................................................................................................................................8
Software template basics...........................................................................................................................9
Template registration..................................................................................................................................13
Catalog inspection for Templates.............................................................................................................15
Instantiating a Template: Scaffolding.......................................................................................................15
POI backend in the Software Catalog.....................................................................................................24
Proxy and frontend Template..................................................................................................................34
Summary...........................................................................................................................................................41
Chapter 6: Building the POI map .......................................................................................................................42
Application development...............................................................................................................................42
Implement the backend.................................................................................................................................42
Write the code............................................................................................................................................42
Check CI/CD..............................................................................................................................................45
Adapt database configuration................................................................................................................46
Check backend app status.......................................................................................................................47
Explore the application’s API....................................................................................................................49
Add the documentation.............................................................................................................................51
Update the catalog....................................................................................................................................56
Implement the proxy and the frontend........................................................................................................62
Write the code............................................................................................................................................62
Check CI/CD..............................................................................................................................................69
Check POI frontend app status...............................................................................................................69
Add POI Map application documentation.............................................................................................70
Update the Software Catalog...................................................................................................................71
Summary...........................................................................................................................................................71
Additional resources........................................................................................................................................71
About the authors................................................................................................................................................72
About the Preview Edition

This fragment invites you into our thinking as we write a developer’s guide to developer
portals. In the first chapter, you’ll learn what an internal developer portal (IDP) is and the
problems addressed by this category of software. To practically apply those ideas, you’ll
examine Red Hat Developer Hub (RHDH), built around the open source Backstage core to
implement an enterprise distribution of a platform for creating developer portals.

Subsequent chapters present some of the tools found in an RHDH instance and their
representation in the RHDH user interface, then show you how to work with those tools to
build an application. By the end of this preview, you’ll know the basics of Backstage Software
Templates and the architecture of the example app.

Note: Because this content is neither complete nor even completely edited, you
should not expect to get that example app running on your own developer portal given
the information in this preview edition alone.

We hope this advance screening will leave you informed about why IDPs are having a moment
and intrigued enough to read the complete first edition when we release it. We’ll do our best
to deliver insights about developer portals in modern development in terms of Backstage and
RHDH, which together represent the pioneering implementation of developer portal
concepts.

Terms used in this book

You’ll see both the names Backstage and Red Hat Developer Hub (RHDH) in this book, which
uses RHDH as a convenient Backstage instance. We don’t exactly use the terms
interchangeably. Directions and examples will usually refer to RHDH, but concepts and terms
that come directly from the upstream Backstage core are named as such. For example, you
might go to the RHDH home page, but you will see references to core concepts like
Backstage Software Templates. This illustrates how Red Hat Developer Hub is a distribution
of Backstage, providing all the core Backstage features, layered beneath essential plug-ins
and configuration tended by Red Hat in the RHDH product. The examples in this book could
be followed stepwise on a generic Backstage instance with little adaptation. But not any
/generic Backstage. You need a Backstage instance configured with the plug-ins for the
implementing services on which the examples depend.

Red Hat Developer

Building and delivering modern, innovative apps and services is more complicated and fast-
moving than ever. Red Hat Developer has the technical tools and expertise to help you
succeed.

The Red Hat Developer program provides many member benefits, including a no-cost
subscription for individuals and access to products like Red Hat Enterprise Linux and Red Hat
OpenShift. Learn more: https://developers.redhat.com/about
Chapter 1: A platform for portals

This is secretly (yet) another book about DevOps.

As a cultural initiative, DevOps has probably made software more reliable and its creation
more rapid. Its best understood practices have benefited their progenitors, publicizers, and
most successful adopters. Developer engagement with deployment concerns engenders a
systems thinking that improves application architecture, but DevOps declares for developers
an unbounded array of new concepts, terms, and concerns.

This increase in cognitive load can make it feel like the early returns from DevOps practices
such as automation and “infrastructure as code” are diminishing and progress slowing. More
than 80% of developers say they have some kind of DevOps responsibility. The more layers
between code editor and cloud deployment a developer has to master, the harder it is to
onboard new teammates and the greater the chances of their burning out in the face of
endless switching into less and less familiar contexts.

The proliferating complexity of simple applications

Think about writing “Hello World.” A few years ago, you’d grab your favorite editor or IDE,
write some code, build it with your compiler or run it through your runtime. Then you’d hand it
off to whoever controlled production when you pushed your locally-tested changes to the
development branch. Your code got built and tested and deployed and had network traffic
routed to it, backing services connected, deployment specifics configured, but little of that
was within your control or even your line of sight.

But DevOps implies a host of new concerns, systems, services, and tools.

Microservices add complexity along another axis. Many pieces of any application. What is it in
the first place? Who is responsible for any given microservice? How do you use its API
facilities? What APIs and other components does it depend on?

Complexity manifolded.

1 Developer Portals: Prepare to Perform with Red Hat Developer Hub

Hello [cruel] World
Writing “Hello World” hasn’t gotten any harder. But running it has. Hello World today means a
running container, built by an automated pipeline (triggered by a source code commit) into a
container image, stored in some registry, with an attendant manifest declaring how it should
be brought to life by a container orchestrator.

There is a lot of stuff to write that is not your application.

So much YAML
Build configuration, CI/CD, container, repository, deployment (Deployment), StatefulSet,
Ingress, Route…

You want this stuff—or you should. And your company definitely wants it. It has a lot of
benefits. But complexity in doing simple things will threaten to impose diminishing returns. In
computing, the answer to complexity is always abstraction.

You’re supposed to be an expert in Java, not an expert on the details of your new team’s AWS
and OpenShift environments, configurations, and prerequisites.

Trade it all for just a little more

Internal developer platforms (IDPs) aim to provide abstraction of development processes,
offering a surface for capturing effective tools, libraries, source boilerplate, and configuration
and centralizing access to them. Ironically, in the IDP ecosystem examined here, simplifying all
that YAML involves… more YAML.

Internal developer platforms

An internal developer platform is a set of tools, services, and practices intended to improve
the productivity and collaboration of software development teams by abstracting and
automating the surrounding complexity of the development and deployment process. An IDP
provides developers with a unified environment for managing application components,
services, and the development lifecycle, including code, infrastructure, and deployment.

IDPs address several key challenges in the software development process, including:

• Complexity: Modern software development involves many tools, services, and

processes. IDPs centralize access to these resources.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 2

 • Collaboration: IDPs promote collaboration by offering shared resources, standardized
workflows, and a consistent experience in a development team.

• Visibility: Developers can’t always see what other teams are working on. IDPs make
large deployment environments more transparent.

• Productivity: By automating repetitive tasks and providing self-service capabilities,

IDPs allow developers to focus on writing code and delivering value.

Backstage: A platform for building developer portals

Backstage is an open source IDP platform created by Spotify, originally to serve their internal
development. The Backstage software has 3 defining features.

• Software catalog: A central repository for the services and components used in a
team or organization, enabling discovery and reuse. Catalog entities index the
disparate resources that go into an application, from source code to build services to
orchestrated deployments.

• Standardized workflows: Designed to capture effective patterns, tools, processing

used by development teams and present them as established paths to development,
Backstage helps enforce best practices and standards.

• Plug-in ecosystem: Backstage supports custom plug-ins and a growing ecosystem of

integration and automation plug-ins. Plug-ins integrate Backstage with infrastructure
services and software components, import patterns and mechanisms, and allow teams
to customize Backstage to integrate their own systems, tools, and methods.

Backstage's purpose is to enhance developer productivity with a single platform for

development activities.

Backstage history
Backstage started at Spotify in 2016. Spotify developers maintain a huge number of
microservices, components, and tools.

Backstage addressed the complexity and diminished visibility attendant to an ever-expanding

set of services and tools—and ever-expanding teams creating and using them. The main idea
was a unified interface for discovering and interacting with all of the resources that comprise
an application. Not just source code, but integration and deployment configuration, source

3 Developer Portals: Prepare to Perform with Red Hat Developer Hub

control, standard versions, languages, and libraries; execution status; rebuild and redeploy
automations—everything.

In 2020, Spotify released Backstage under the open source Apache license, allowing other
organizations to benefit from the platform and contribute to its improvement. Developers and
companies adopted the project in response, many of them contributing new features, abilities,
and fixes to the upstream code base. A Backstage ecosystem has grown around the core
software as well, with plug-ins and integrations developed to extend its functionality.

In 2022, the Cloud Native Computing Foundation (CNCF) accepted Backstage as an

incubating project. This solidified Backstage's position as a principal implementation of IDP
concepts and standardized the project’s governance within the CNCF landscape.

Backstage today: Project and ecosystem

Backstage is an open source platform designed as the foundation of an internal developer
portal. Above, you saw the three key software expressions of Backstage’s purpose. Those
features are how Backstage abstracts complexity and provides paved roads to standard tools
and practices. When resources are documented, discoverable, searchable, and their
dependencies and ownership clear, teams benefit in several ways.

Backstage promotes collaboration by providing visibility into what different teams are working
on. Transparency helps prevent duplication of efforts, encourages reuse of services and
components, and fosters a sense of community among development teams.

Backstage can automate tasks such as creating new services or components, provisioning
infrastructure, and generating documentation. Automation reduces manual overhead and lets
developers focus on writing code.

Teams can customize Backstage with features and plug-ins to fit their specific requirements.
Since Backstage has a growing community of contributors and adopters, new features,
integrations, and improvements appear frequently.

Red Hat Developer Hub

Akin to familiar Red Hat flagship products like Red Hat Enterprise Linux and Red Hat
OpenShift, Red Hat Developer Hub (RHDH) is an enterprise distribution with an open source
project at its core. Harnessing the Backstage core code together with curated plug-ins, day-
two configuration, and ready-made Golden Path Templates for common development

Developer Portals: Prepare to Perform with Red Hat Developer Hub 4

scenarios, RHDH in turn has an open source “midstream” project, called Janus, where
community development efforts are organized and publicly conducted.

Like Backstage, Red Hat Developer Hub is a platform for building developer portals. There is
always platform engineering work, with or without that formal title. Identifying patterns and
standards and refining them in line with organization goals is a key part of getting value out of
your site’s developer portal. RHDH makes it easier for you to get started with the examples in
the book by avoiding a lot of secondary decisions about integrations, configuration, and
features that you’d need to make if you started from scratch with the upstream Backstage
code.

Summary
Every team and every project evolves a tailored development environment. This collection of
tools, services and configuration is often maintained by convention and transmitted by
osmosis.

Internal developer portals help teams curate, manage and replicate these environments.
Backstage is an open source CNCF project for building developer portals, and for
encapsulating tools, services, documentation and best practices in “golden paths” to ease
onboarding and daily development. Red Hat Developer Hub is Red Hat’s enterprise IDP
platform, curating Backstage core and the ecosystem around it.

5 Developer Portals: Prepare to Perform with Red Hat Developer Hub

Chapter 5: Templates: Application
head start

Software Templates are a Backstage feature for flexibly defining a starting point for some
arbitrary kit. A Template might represent a place to begin work on a new application built with
some standard language or framework, for example, potentially including executables,
runtimes or compilers of standard versions, boilerplate code, build configurations, and the like.

You’ll investigate Templates by adding to your running Red Hat Developer Hub portal a pair of
templates that represent a starting point for working on a web application. Then you’ll
instantiate from those Templates with the portal’s Create function to generate all the
scaffolding for your new application: source code boilerplate in a Git repo, pipelines to build it,
manifests to deploy it on Kubernetes or OpenShift.

The Point of Interest Map application

The exercises in this book center on an example application that displays a world map you can
pan, zoom, and click to investigate arbitrary points of interest (POI).

You’ll construct the application atop a set of Templates that define and deploy foundation
components, then use Red Hat Developer Hub’s Software Catalog, API index, and other
facilities to implement the application and extend it with new features.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 6

 Figure 5-1: The POI Map Application user interface.

Application specifics

Structure and technologies

The POI map application has 4 parts:

• A relational database that stores the point of interest records (PostgreSQL).

• A backend application exposing a REST API to serve the points of interest from the
database (written in TypeScript with NestJS).

• A proxy application sitting as a facade between the backend and frontend to

delegate web client requests to the backend’s REST API accordingly (written in Java
with Quarkus).

• A single-page application (SPA) to provide the user interface where the map is
displayed (written in TypeScript with Angular).

Architecture
While the backend, proxy, and frontend parts of the map application could be individually built
and separately deployed, it makes sense to simplify the architecture a bit. The SPA frontend is
embedded with the API client component, served with the Quarkus http server methods. This
gives the POI Map application an architecture of three primary pieces: the frontend/API client
machinery, the NestJS POI API backend, and the database.

7 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 5-2: POI application architecture.

Software templates
Template structure
A Software Template is stored in its own source control repository, then registered in a given
RHDH instance’s software catalog.

The two Templates defining the foundations of the POI Map application use the same folder
structure:

my-template (1)
├── manifests (2)
├── skeleton (3)
└── template.yaml (4)

where:

1. my-template: The top-level directory containing all template resources.

2. manifests: The manifests subdirectory holds the YAML files, Helm charts, and
other declarations related to the deployment of the application.

3. skeleton: The skeleton subdirectory holds the basic source code structure of the
application.

4. template.yaml: A YAML file defining a Backstage catalog entity of the kind

Template.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 8

 Figure 5-3: Application architecture expressed in two Templates.
The scaffolding to support the three-part architecture of the map application is split between
two templates. The first template deploys the backend application together with its database.
The second template creates the framework for the frontend and API client.

Software template basics

As you saw in the Template directory listing above, the template.yaml file at the root of the
template directory defines a Backstage Software Template. A template manifest is structured
around a few major YAML stanzas.

First, the metadata block describes the Template and defines its owner and the Backstage
entity type created by instantiating it—in this case, an entity of type service.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: a-simple-template
title: A simple template
description: This simple template is used for learning purposes.
spec:
owner: rhdeveloper-book-authors
type: service

Next, the parameters array declares the elements of the configuration form presented when
someone selects a Template and creates a new instance of the entities defined in it. The

9 Developer Portals: Prepare to Perform with Red Hat Developer Hub

parameters array describes configuration that varies between deployments of a Template’s
resources so that you can change it as appropriate for a new instance.

Given the example parameters stanza shown here, each new instance of this Template will
expect you to enter or choose a number of configuration items, including the source
repository where Template resources should be created, and the RHDH user who owns the
entities created from the template. While this book is a guide to using Backstage and Red Hat
Developer Hub rather than a guide to platform engineering topics like template creation, it is
helpful to see how a template author defines the Template instance configuration form.
Notice in the Name property that parameters can have a default value. The Owner property
defines a selection pop-up menu and the items on it.

parameters:
- title: Enter some (required *) component parameters
required:
- name
properties:
name:
title: Name
type: string
description: unique name for this component
default: my-component-123
owner:
title: Owner
type: string
description: owner of this component
ui:field: EntityPicker
ui:options:
catalogFilter:
kind: [User]
- title: Choose a repository location
required:
- repoUrl
properties:
repoUrl:
title: Repository Location
type: string
ui:field: RepoUrlPicker
ui:options:
allowedHosts:

Developer Portals: Prepare to Perform with Red Hat Developer Hub 10

 - github.com
- gitlab.com

The preceding YAML snippet renders as a form like this in RHDH’s web UI. The component’s
name and owner can be specified in the first form section (Figure 5-4).

Figure 5-4: Template Parameters Form Wizard section 1.

In the second form (Figure 5-5), the Template gathers where to scaffold the entity’s source
code repository. In this Template, host can be either github.com or gitlab.com, selected from a
drop-down menu. The user or organization Owner and the repository name are also
configured in this section.

Figure 5-5: Template Parameters Form Wizard Section 2.

11 Developer Portals: Prepare to Perform with Red Hat Developer Hub

The third section is where the templating magic actually happens. The steps array defines
the sequential actions that are executed by the scaffolder backend in RHDH:

steps:
- id: templateSource
name: Generating the source code component
action: fetch:template
input:
url: ./skeleton
targetPath: ./source
values:
name: ${{ parameters.name }}
- id: publishSource
name: Publishing to the source code repository
action: publish:github
input:
sourcePath: ./source
description: Source code repository for component ${{ parameters.name }}
repoUrl: ${{ parameters.repoUrl }}
defaultBranch: main
repoVisibility: public
- id: registerComponent
name: Register component into the catalog
action: catalog:register
input:
repoContentsUrl: ${{ steps.publishSource.output.repoContentsUrl }}
catalogInfoPath: '/catalog-info.yaml'

This excerpted steps array defines 3 step actions:

1. templateSource → fetch:template downloads source boilerplate from the

template’s origin repository, expands variables declared in the parameters, replacing
their tokens with the appropriate values within files and file names, finally placing the
result in the configured repository, or optionally in a subdirectory specified by the
targetPath variable.

2. publishSource → publish:github initializes a git repository based on the

templated source from step 1 and pushes it to GitHub. There are similar actions
available for other Git hosting services, for instance, GitLab or BitBucket.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 12

 3. registerComponent → catalog:register registers entities into the software
catalog based on a catalog description file. Conventionally named catalog-
info.yaml, this file is read from the Git repository created in step 2.

Template registration
You need to tell the portal about a new Template in order to work with it. In an organization
with an established RHDH or Backstage instance, daily development probably won’t involve
registering new Templates as often as it will involve creating new entities from provided
Templates and monitoring and working with entities already created and indexed in the
Software Catalog. But you’ll have to register the two POI application Templates on your new
and mostly empty RHDH instance, so here is a look at how Template registration works.

There are two ways to add Templates and make them available to the portal’s Create
functions. First, RHDH inherits app-config.yaml, Backstage’s main portal configuration
file. This file declares configuration for the life of a running portal instance, including
references to Template source URLs. The portal must be restarted to change this static
configuration.

Templates can instead be added dynamically through the Register existing component
item found in the Create view. Again, you inform the portal about new Templates by
reference to their source URL.

You can use the dynamic approach just described to add the two templates from their
respective repository location:

• Go to + Create → Register existing component and copy the full HTTP URL to the
template.yaml file in the nestjs-with-postgres folder of the Git repository.
Paste the URL into the form’s (1) Select URL field, as shown in Figure 5-6.

13 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 5-6: Template registration into the Software Catalog, step 1.

• Clicking the ANALYZE button shows that two entities will be added into the software
catalog. One entity is the location, the HTTP URL from where the template was
loaded, and the other entity is the template itself.

• Click the IMPORT button to confirm (Figure 5-7).

Figure 5-7: Template registration

into the Software Catalog, step 2.
• Click the REGISTER ANOTHER button (Figure 5-8). This brings you the same
registration form wizard where you can register the second template. Copy the HTTP

Developer Portals: Prepare to Perform with Red Hat Developer Hub 14

 URL of the template.yaml file in the quarkus-with-angular folder of the Git
repository into the form’s (1) Select URL field and continue as you did for the first
template.

Figure 5-8: Template Registration

into the Software Catalog, step 3.

Catalog inspection for Templates

Go to the Software Catalog and filter for Kind > Template to see the two new templates.

Figure 5-9: Show Templates in Software Catalog.

Instantiating a Template: Scaffolding

With the two map application Templates available to the portal’s Create functions, you’re
informed about how Software Templates work and how to add Templates to your RHDH

15 Developer Portals: Prepare to Perform with Red Hat Developer Hub

portal. From here, you’re ready to start where most developers would: using a Template to get
the basics in place for building a new application.

Backend Template
Begin by creating an instance from the nestjs-with-postgres template. This template
scaffolds the source repository for the backend service, builds the code in it, and deploys the
result along with the database server on which the backend relies.

Go to + Create and select the Template NestJS Service with backing PostgreSQL
database by clicking the CHOOSE button in the lower-right corner of the template tile.

Figure 5-10: Portal Create view with Template tiles.

Template form wizard

This brings you to the template’s form wizard where you can configure certain elements of the
template. In the first section of this form (Figure 5-11), you define the GitLab location where
the resulting source code and GitOps repositories should be stored.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 16

 Figure 5-11: NestJS Service Template configuration form, first section.

In the second section, you specify the who, what, and where of the application resources to be
scaffolded from the Template. The cluster ID and namespace where the running application
should be deployed, what application ID names it, and the user who owns it. You’ll see this
metadata reflected in descriptions, data about, and links between entities in the Software
Catalog after you submit the Create forms and scaffolding is complete.

Figure 5-12: NestJS Service Template configuration form,

second section.

17 Developer Portals: Prepare to Perform with Red Hat Developer Hub

The third form section (Figure 5-13) specifies the container image registry where the
application containers should be stored and available to the cluster orchestrator (OpenShift in
the book’s exercises). You can also optionally set a tag for the container image. The default,
latest, is acceptable for the purposes of building the example application, although it is not
usually a best practice for production.

Figure 5-13: NestJS Service Template configuration form, third section.

Clicking the NEXT STEP button shows you a summary of all the entered form fields for a
final review (Figure 5-14).

Figure 5-14: NestJS Service Template configuration form, final review.

Click CREATE to kick off the process of scaffolding application resources from the Template.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 18

Template scaffolding process
The NestJS Service backend Template is composed of six sequential steps, each of which
represents either a built-in or a custom scaffolder action available in your running RHDH
portal:

1. fetch:template: Fetches the template from its location and recursively walks
through all source folders and files (see skeleton sub folder at the origin). In each
file, the scaffolder checks if it finds variables and needs to perform parameter
replacements based on the settings which have been entered upfront in the form
wizard. More details about the templating syntax can be found in the Backstage
documentation.

2. publish:gitlab: All processed source files resulting from the templating process in
step 1 are then published into a source code repository for this component according to
the GitLab settings.

3. fetch:template: Similar to step 1, it will fetch the template contents from its location
and recurse through the manifest files (see manifest sub folder at the origin) to
potentially perform parameter replacements in the files’ contents based on the
settings that have been entered.

4. publish:gitlab: All processed manifest files resulting from the scaffolding process
in step 3 are then published into a GitOps repository for this component according to
the GitLab settings.

5. catalog:register: Using the information found in the scaffolded source code

repository’s catalog-info.yaml file, the component is registered in the software
catalog. To learn more about the descriptor format, check out the official docs page.

6. argocd:create-resources: Instructs Argo CD to take action and start processing

what has been scaffolded and published into the GitOps repository in steps 3 and 4,
respectively.

19 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 5-15: NestJS Service
Template scaffolding.

Figure 5-16: Describing the fetch-template action and its parameters.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 20

Template steps can use built-in actions and custom actions written for a team’s specific
needs. To see which actions are installed in your RHDH instance, navigate to
http(s)://<YOUR_BACKSTAGE_BASE_URL>/create/actions. This page shows the
instance’s available actions, including a brief description of each and the parameters it
accepts.

Figure 5-17: Example usage for the fetch-template action.

There’s a lot going on when you click Create and kick off the process of scaffolding from a
Template. If you imagine yourself encountering a portal where this template is already
available, the value of the developer portal comes into clearer focus. Think of bouncing
between service UIs and auth systems to manually perform all the steps automated by the
template actions, from source control in GitLab, to GitOps processes to continually build from
source with Argo CD and Tekton pipelines. You can see a depiction of the services harnessed
together by the Template scaffolding process in Figure 5-18.

21 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 5-18: RHDH GitOps automation: Portal, GitLab, Argo
CD, Tekton, OpenShift.

RHDH first reads the template contents from GitLab and then writes the scaffolded source
code as well as the resulting GitOps related repository to GitLab. Then the portal instructs
Argo CD to create all the specified resources in the target Kubernetes cluster and namespace.
The POI map example Templates generate manifests in the form of Helm deployment charts
that declare:

• A CI pipeline in Tekton and a webhook event listener that is triggered on every commit
to the source code repository (see the helm/build folder of the related GitOps
repository).

• Everything needed to deploy the backend application, which in this simple case is a
Kubernetes Deployment, Service, and Route, along with the database (see the
helm/app folder of the related GitOps repository).

Template results
Continuing with the itemization of the steps automated by RHDH in its process of scaffolding
resources from the backend Template, take a look at the GitOps resources the scaffolder puts
in place:

• Two new repositories, demo01-poi-backend and demo01-poi-backend-gitops,

dividing application source from CI/CD automation resources.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 22

 Figure 5-19: GitLab repositories for the POI backend.

• Three Argo CD “applications” (bootstrap, build pipeline, actual application, shown in

Figure 5-20) for the build and deployment automation that form the basis of GitOps
practices. These Argo applications are among the resources declared in the files
beneath the *-gitops repo.

Figure 5-20: Argo CD applications for the POI backend.

• The deployed application, comprising the NestJS service and its PostgreSQL
database. The build pipeline and the webhook that triggers rebuilds and redeployments
when source code changes are committed also run on the deployment target cluster,
seen in the OpenShift web console in Figure 5-21.

23 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 5-21: OpenShift topology view with the POI backend.

POI backend in the Software Catalog

The Template scaffolding process added an entry to the Software Catalog for the POI
backend, demo01-poi-backend. Switch to the Catalog View in the RHDH left navigation to
see it.

Figure 5-22: POI Backend entity in the Software Catalog.

You can inspect a component by clicking on its name to open the component Overview.

Note: The available tabs in the Component view depend on the configuration of the
RHDH instance.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 24

 Figure 5-23: POI backend component Overview tab.

In the next sections, you will briefly visit the different tabs from that component detail view to
figure out what you can learn about this registered catalog component that represents the
backend service of the POI map application.

The component screens in RHDH represent everything known about this application, derived
from component metadata, information from plug-in integrations with infrastructure services,
like Argo CD, Tekton, and the OpenShift (or Kubernetes) cluster where executables run.

Overview tab
The Overview tab displays a few tiles such as an About section with direct access to the
source code repository (View source) and technical documentation (View TechDocs). In
the upper-right corner of a Component Overview’s About tile you can do the following:

• Edit the underlying catalog-info.yaml contents in the corresponding git repository

to make changes to this catalog component

• Trigger the portal to re-read the Component’s catalog-info.yaml and update the
Component with the new configuration and metadata

The available information displayed in the details view and its different tabs is directly and
largely based on the component’s catalog-info.yaml file. To give a simple example, the
links tile holds custom component links which are found in the links section of this
component’s YAML definition:

25 Developer Portals: Prepare to Perform with Red Hat Developer Hub

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: demo01-poi-backend
description: Creates a NestJS Service together with a PostgreSQL database
annotations:
argocd/app-name: demo01-poi-backend-dev
backstage.io/kubernetes-id: demo01-poi-backend
backstage.io/kubernetes-namespace: demo01
backstage.io/techdocs-ref: dir:.
gitlab.com/project-slug: development/demo01-poi-backend
janus-idp.io/tekton-enabled: 'true'
tags:
- nodejs
- nestjs
- book
- example
links:
- url: https://console-openshift-console.apps.cluster-
nxfzm.sandbox2909.opentlc.com/dev-pipelines/ns/demo01/
title: Pipelines
icon: web
- url: https://console-openshift-console.apps.cluster-
nxfzm.sandbox2909.opentlc.com/k8s/ns/demo01/deployments/demo01-poi-backend
title: Deployment
icon: web
- url:
https://devspaces.apps.cluster-nxfzm.sandbox2909.opentlc.com/#https://gitlab-
gitlab.apps.cluster-nxfzm.sandbox2909.opentlc.com/development/demo01-poi-backend?
che-editor=che-incubator/che-code/latest&devfilePath=.devfile-vscode.yaml
title: OpenShift Dev Spaces
icon: web
spec:
type: service
lifecycle: production
owner: "user:default/user1"
system: idp-system-demo01
providesApis:
- demo01-poi-backend-api
dependsOn:
- resource:default/demo01-poi-backend-db

Developer Portals: Prepare to Perform with Red Hat Developer Hub 26

Toward the end of this component definition you can see information about the owner,
relationships regarding the logical grouping of components into a system, but also whether or
not there are provided or consumed APIs for this component (providesApis), and if
dependencies to other components and/or infrastructure resources (e.g., databases,
messaging queues, caches) exist (dependsOn).

Topology tab
The Topology plug-in provides a tab in the Component view showing the component’s
resources on a deployment target OpenShift or Kubernetes cluster. These include the usual
application resources in Kubernetes API terms, such as Deployment, Job, Daemonset,
Statefulset, CronJob, and Pod. When you click on the POI backend deployment, a side pane
slides in from the right to show more details. You can even retrieve logs from the container
running in the pod directly in the portal’s Component view.

Figure 5-24: POI Backend component Topology tab.

Find more information about how to install, configure and use the Topology plug-in in the
documentation.

Issues and Pull/Merge Requests tabs

As a developer, you need to be aware of project issues as well as incoming changes from other
developers. You can see this activity in your portal’s Component views. Based on plug-ins,
RHDH can integrate with various Git hosting services such as GitLab, GitHub, and others to
retrieve and display issues and pull/merge requests, respectively. Since the component was

27 Developer Portals: Prepare to Perform with Red Hat Developer Hub

freshly scaffolded and just registered in the catalog, unsurprisingly, both these tabs are
currently empty. You will revisit them during the development of the application specific code.

Figure 5-25: POI backend component Issues tab.

Figure 5-26: POI Backend component Pull Requests tab.

CI tab
In the CI tab, you can explore the build pipelines for the component in question. This view isn’t
limited to just one type of continuous integration, but if applicable, can conveniently display
multiple CI-related activities for the same component. In your example, and as shown in
Figure 5-27, there are two different pipelines, namely:

• a GitLab pipeline that is used for building and publishing the technical documentation
for the component.

• a Tekton pipeline used to create the container image for the backend service.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 28

 Figure 5-27: POI backend component CI tab.
CD tab
In this example, the CD-related information is retrieved from Argo CD by means of another
plug-in. What’s shown is a basic tabular history of the Argo CD application managing the
component’s deployment.

Figure 5-28: POI backend component CD tab.

Besides that, the component’s Overview tab (already discussed; see Figure 5-23) also
contains a specific tile that displays Argo CD data, most notably the sync and health status
and the last synced timestamp.

29 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 5-29: POI backend component Overview tab Argo CD tile.

Find more information about how to install, configure and use this plug-in in the
documentation.

Kubernetes tab
In this tab, the various pods—underpinning the catalog component—that are running in the
target Kubernetes cluster can be inspected including some workload-related details. This is
very handy, in particular, when there are any issues or errors with some of these pods.

Figure 5-30: POI backend component Kubernetes tab.

Tekton tab
The build pipeline that has been pre-configured as part of the software template and
deployed by Argo CD is available in the Tekton tab. It provides a tabular listing with previous
pipeline runs together with the most relevant information for each run.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 30

 Figure 5-31: POI backend component Tekton tab.

A click on any of the listed pipeline runs shows the separate pipeline steps/stages and their
respective outcomes (Figure 5-32). It’s also possible to retrieve the logs for each step/stage
individually by clicking on it.

Figure 5-32: POI backend component Tekton tab

pipeline run details.
Find more information about how to install, configure and use this plug-in in the
documentation.

API tab
Whether or not components either consume APIs from other components and/or provide
APIs themselves, including API ownership information as well as system relationships if
applicable, is all shown in the API tab. The scaffolded backend application provides an API
which can be further investigated by clicking on its name. However, since this is currently a
“hello world” REST endpoint, a more detailed discussion concerning API-related RHDH
features follows at a later stage. We will revisit this view after we have implemented and added
the actual API for the POI backend service.

31 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 5-33: POI Backend component API tab.

Dependencies tab
Components very rarely live in isolation but instead, are often logically grouped together to
form a superordinate system. In addition to that, components can directly depend on yet
other components or resources such databases, caches, messaging infrastructure and the
like. The Dependencies tab provides insights into these aspects, thankfully even with nice
diagrams which greatly help with understanding more complex component hierarchies and/or
relationships between components and resources alike.

Figure 5-34: POI Backend component Dependencies tab.

For the registered backend component you can see at a first glance:

• who owns it (user1);

Developer Portals: Prepare to Perform with Red Hat Developer Hub 32

 • which resource—in this case, database—it depends on (demo01-poi-backend-db);

• that it provides an API (demo01-poi-backend-api);

• and that this component is part of a system (idp-system-demo01).

As more components will be added by means of applying further templates and by properly
maintaining all these relationships in the respective catalog-info.yaml files during the
development phase, such diagrams will grow and thus become more valuable in making sense
of larger and more complex systems.

Docs tab
Having technical documentation for registered catalog components is vital. The core idea is to
live a “docs-like-code” approach. Under the covers, the default way to write documentation is
based on Markdown and the documentation related files are co-located in the same
repository as the component’s source code. What the Docs tab shows is the latest available
version of a component’s rendered HTML documentation, which has been generated and
published as part of the configured CI pipeline.

Figure 5-35: POI backend component Docs tab.

The backend component has a working TechDocs setup as configured and scaffolded during
the templating phase. Two really handy features, which are explored more closely later during
the application development phase, are:

• Modifying the underlying Markdown file: By clicking the edit icon in the upper
right, the user is redirected to the specific Markdown file in the component’s source
code repository. This is where changes can directly be made. Thanks to the configured
CI pipeline, any changes are triggering a new pipeline run. Once this is finished, a
refresh of the documentation page in the Docs tab will show the updated contents
immediately.

• Opening a documentation-related issue: By marking / highlighting some text on

the documentation page and clicking Open GitLab / GitHub / … issue, you are

33 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 redirected to the issue creation page of the Git repository. This makes it easy to create
an issue to signal problems with the documentation to the maintainers/owners of the
catalog entity.

Proxy and frontend Template

Now that the backend component’s source code and GitOps repositories are in place, you
continue by applying the second custom template—the quarkus-with-angular template—
which addresses the proxy and frontend parts of the POI Map application. Go to + Create
and select the template Quarkus Service with hosted Angular Frontend by clicking the
CHOOSE button in the lower-right corner of the corresponding template tile.

Figure 5-36: Portal Create view with Template tiles.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 34

Template form wizard
This brings you into the template’s form wizard where you can parameterize certain elements
of the template in question. You’ve been here before when scaffolding the backend
component from the first template. What you are going to do here is strikingly similar.

In the first section of this form, you define information about the GitLab location used for
publishing the resulting source code and GitOps repositories—leave the defaults as is.

Figure 5-37: Quarkus Service with Angular Template configuration form, first section.

In the second section, you specify important settings, namely, cluster ID, namespace,
application ID and owner for our new software component. Based on this information, it’s
clear into which Kubernetes cluster and namespace this component is eventually going to be
deployed with the entered application ID as its name. The selected user defines the
ownership for this software component. It’s important to make sure that you use the same
namespace and cluster ID as for the backend template you applied earlier (see Template form
wizard).

35 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 5-38: Quarkus Service with Angular Template configuration form, second
section.

In the third step, it’s defined which image registry to use for pushing the container image to.
You can also choose a custom tag that gets used during the CI process to tag the container
image with.

Figure 5-39: Quarkus Service with Angular Template configuration form, third
section.

Clicking NEXT STEP shows a summary of all the entered form fields for a final review.

Finally, hit CREATE to kick off the actual templating process.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 36

 Figure 5-40: Quarkus Service with Angular Template configuration form, final review.

Figure 5-41: Quarkus Service with Angular Template scaffolding results.

Template scaffolding process

Insights into what’s happening during the scaffolding process under the covers have been
provided in detail for the backend template already. Feel free to revisit the corresponding
book section (see Template Scaffolding Process) if necessary.

37 Developer Portals: Prepare to Perform with Red Hat Developer Hub

Template results
As a result of applying this template, you end up with the following resources created on your
behalf:

• In GitLab you have two new repositories (Figure 5-42), demo01-poi-map and
demo01-poi-map-gitops.

Figure 5-42: GitLab repositories for the POI frontend.

• In Argo CD there are 3 new “applications”(bootstrap, build pipeline, actual application)

for GitOps, as shown in Figure 5-43.

Figure 5-43: Argo CD applications for the POI frontend.

• In Kubernetes, there is the deployed Quarkus proxy application, which also serves the
Angular single-page application frontend. Additionally, the build pipeline and the
webhook-related resources have been set up.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 38

 Figure 5-44: OpenShift topology view with the POI backend and frontend.

POI proxy service and frontend in the Software Catalog

In contrast to the backend template, the major difference with this template is the fact that
you end up with two separately registered catalog components. This is intentional, and results
from the “monorepo” approach that has been chosen when creating the template for this
proxy service that embeds the frontend application. Switch to the Catalog View in Red Hat
Developer Hub to locate and explore your two new software catalog components, demo01-
poi-map-frontend (Angular single-page application) and demo01-poi-map-service
(Quarkus proxy).

Figure 5-45: POI proxy service and frontend entities in the Software Catalog.

39 Developer Portals: Prepare to Perform with Red Hat Developer Hub

You can inspect various details and important information about both these components by
clicking on their respective names in the tabular listing to open a specific component’s detail
view.

Note: Keep in mind that the actual possibilities, the available tabs, and the tiles
anywhere in that detail view primarily depend on the configuration of the RHDH
instance, the installed plugins as well as any component view customizations which may
or may not be in place for your environment.

Since you have already visited the different tabs for a component’s detail view earlier while
exploring the demo01-poi-backend component of the POI map application (see POI
backend in the Software Catalog), this should all look very familiar to you at that stage—at
least for the demo01-poi-map-service component. Nevertheless, it’s worth noting some
differences by taking a closer look at the demo01-poi-map-frontend component. By
clicking on its name in the catalog, you end up in the component overview, as shown in Figure
5-46.

Figure 5-46: POI frontend component overview tab.

When you open certain tabs for this component, you will realize some of them are empty.
Let’s visit the empty ones to better understand what is going on for the demo01-poi-map-
frontend component and why:

• Topology and Kubernetes tabs: Both are telling you there are no dedicated
resources found for this specific component. That’s fine because the Angular SPA is
hosted and served from within the Quarkus proxy service, meaning it’s the same
resources for Deployment, Pod, etc., as for the demo01-poi-map-service
component.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 40

 • CD tab: RHDH complains about a missing argocd/app-name annotation. The
templated catalog-info.yaml didn’t provide one on purpose, because no Argo CD
managed resources are necessary for the Angular SPA itself. Because it’s part of the
Quarkus proxy service, it’s the same Argo CD resources as for the demo01-poi-map-
service.

• Tekton tab: This informs you that no pipeline runs are found, which is also kind of
expected, because the Angular SPA is built together with the Quarkus proxy service
(see demo01-poi-map-service) in the same Tekton-based build pipeline

• Docs tab: RHDH complains about a missing backstage.io/techdocs-ref

annotation. The templated catalog-info.yaml intentionally left it out and assumes
this component to be documentation together with the Quarkus proxy service (see
demo01-poi-map-service).

Just to clarify, of course it would work to treat both these components completely separately.
However, we’ve chosen this architecture for the proxy service and the frontend application
paired with the monorepo approach in order to show RHDH’s flexibility for working with
templates and software catalog components in different ways.

Summary
You’ve explored the basics of how Software Templates are defined, then used two example
Templates to deploy the foundation atop which you’ll implement the POI Map application. In
your running portal, the Software Catalog lists three new entities indexing all of the resources
of your development project, from source code to the executing components of the
application.

In the next chapter, you’ll add code to the scaffolding provided by the Templates to create a
functional POI map.

41 Developer Portals: Prepare to Perform with Red Hat Developer Hub

Chapter 6: Building the POI map

Application development
You’ve used a couple of Software Templates to put everything in place to get a new
application going. Now you can implement your application features with actual code. While
you’ve peered inside a Template and registered it in your portal, often your usual work would
begin nearer to this point, making changes to existing entities indexed in your Software
Catalog.

Implement the backend

You scaffolded the POI backend from the nestjs-with-postgres template in the last
chapter. This included a skeletal source code repository. So far, the repo contains only a
simple Hello World NestJS application.

Write the code

Click Catalog in the Red Hat Developer Hub left-hand navigation and select the demo01-
poi-backend component. In the component’s details view, jump to the corresponding
GitLab source code repository by clicking the View Source link in the About tile of the
Overview tab. From the GitLab page of the repository, use Clone URL to create a local
clone for developing the application code.

After cloning this repository, open the NestJS project in the IDE of your choice. At that point,
you could start to develop the code for the application in question. To speed things up, we
provide a turn-key ready implementation for this backend service in a ZIP archive.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 42

 Figure 6-1: POI backend repository in GitLab.

After downloading the ZIP archive to your development machine, perform the following
commands at a terminal prompt in your IDE or OS:

1. Unzip the archive: unzip -r archive.zip

2. Copy all the contents from inside the root folder of the unzipped archive:

cp -r archive/* demo1-poi-backend

3. Inside the project’s root folder (demo01-poi-backend): cd demo1-poi-backend

1. Create a new Git branch: git checkout -b app-dev

2. Run git add .

3. Run git status. You should see a changeset like the following:

On branch app-dev
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
new file: .env
modified: Dockerfile
new file: assets/nationalparks.json
modified: openapi.yaml
modified: package-lock.json
modified: package.json
new file: prisma/migrations/init/migration.sql
new file: prisma/migrations/migration_lock.toml
new file: prisma/schema.prisma
deleted: src/app.controller.spec.ts
deleted: src/app.controller.ts
modified: src/app.module.ts

43 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 deleted: src/app.service.ts
modified: src/main.ts
new file: src/poi/db.service.ts
new file: src/poi/poi.controller.ts
new file: src/poi/poi.record.ts
new file: src/poi/poi.service.ts
new file: src/proxy/backend.controller.ts

4. Commit these application code changes and push the new app-dev branch to
the GitLab repository: git commit -m ‘implement poi backend’

5. In the GitLab web UI, create a new merge request for your app-dev branch.

Figure 6-2: GitLab open merge request for app-dev branch.

Once the merge request has been created, you can view it by switching to the component’s
details view in RHDH and select the Merge requests tab.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 44

 Figure 6-3: POI backend component view pull Pull/Merge Requests tab in RHDH.

Back in GitLab, you can merge this merge request (Figure 6-4).

Figure 6-4: GitLab merged merge request for app-dev branch.

Check CI/CD
The merged code will trigger the configured build pipeline via a webhook. After a minute or
so, the code changes are available in the freshly built container image for your backend
service.

45 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 6-5: POI backend component view Tekton tab in RHDH.

Adapt database configuration

Since the backend service now uses a database table named poi with a specific table
structure, you need to provide a SQL DDL snippet to configure Helm’s provisioning of the
PostgreSQL database.

Open the backend’s GitOps repository, demo01-poi-backend-gitops, in GitLab. As the

change to be made is a rather trivial one, you might take a shortcut here rather than going
through a full development cycle including feature branches and merge requests. Edit the
Helm chart’s values.yaml file directly in GitLab to add the following DDL snippet:

initdb:
scripts:
db_init.sql: |
-- CreateTable
CREATE TABLE "Poi" (
"id" BIGSERIAL NOT NULL,
"name" TEXT NOT NULL,
"description" TEXT,
"latitude" DOUBLE PRECISION NOT NULL,
"longitude" DOUBLE PRECISION NOT NULL,
"type" TEXT NOT NULL,

CONSTRAINT "Poi_pkey" PRIMARY KEY ("id")

);

Developer Portals: Prepare to Perform with Red Hat Developer Hub 46

To do so, locate the file helm/app/values.yaml in the GitLab repository demo01-poi-
backend-gitops and append the preceding snippet. This will make sure that the database
table your backend service needs gets created during the database bootstrapping phase.
With the DDL in place, click the Commit changes button to confirm your change.

Figure 6-6: Edit Helm chart’s values.yaml in GitLab to add SQL init script.

This change in the GitOps repository will eventually trigger another build pipeline run and
consequently also lead to a redeployment of the Postgres database instance by Argo CD.

Check backend app status

With the necessary application changes done, let’s figure out if your backend service is
running correctly. Open the demo01-poi-backend in the RHDH catalog component view
and switch to the Topology tab. Click on the deployment and select Resources from the
right-side pane.

47 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 6-7: POI backend component Topology tab deployment resources.
The pod seems to be running fine. You can explore the logs by clicking View Logs next to the
running pod information; you should see a log output similar to the one in Figure 6-8.

Figure 6-8: POI Backend component pod logs view

This indicates that the backend service should be up and running fine. After closing the logs,
you can click on the Routes link, which opens a new browser tab. Because the backend service
isn’t serving anything on the / path, the error message shown in the new tab is expected.

{"message":"Cannot GET /","error":"Not Found","statusCode":404}

By appending /ws/info at the end of the current URL, you should see the following
response:

{"id":"poi-backend","displayName":"National Parks","coordinates":
{"lat":0,"lng":0},"zoom":3}

Developer Portals: Prepare to Perform with Red Hat Developer Hub 48

If you change the end of the URL to the path /poi/find/all, you are supposed to get a
response with plenty of JSON output for all the loaded POIs from the database, which
represent national parks across the world.

Explore the application’s API

Your NestJS backend service offers a Swagger UI based on the underlying OpenAPI
specification. You can inspect the exposed REST API by switching to the API tab in the
catalog component’s detail view (Figure 6-9) and then clicking on the one entry demo01-
poi-backend-api in the Provided APIs table.

Figure 6-9: POI backend component API tab.

In the API view, there is a Links tile as part of its Overview tab that has two entries:

• Swagger UI: A direct link to the swagger UI as served by the running backend service.

• API Spec: A direct link to this API’s underlying openapi.yaml, which resides in the
component’s source code repository.

Figure 6-10: POI backend API Overview tab.

49 Developer Portals: Prepare to Perform with Red Hat Developer Hub

Clicking the Swagger UI link opens a new browser tab to inspect and experiment with the
exposed API methods from the Swagger web UI (Figure 6-11).

Figure 6-11: POI backend API Swagger UI.

Clicking the API Spec link opens the GitLab repository showing the openapi.yaml file.

Figure 6-12: GitLab Swagger UI for the POI backend OpenAPI spec.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 50

Viewing the file contents rather than the rendered Swagger UI within GitLab is also possible
by clicking Open Raw in the upper-right corner.

Figure 6-13: GitLab raw file view for openapi.yaml definition of POI backend.

Add the documentation

Now that the application is up and running fine, you can shift your focus to another important
aspect, which is documentation. You learned in the Applying templates section that
everything necessary to follow a “docs-like-code” approach is pre-configured and in place
right from the beginning. This means you can fully focus on writing documentation itself—no
need to worry or explicitly care about generating and publishing documentation updates
based on changed documentation sources.

To experience how convenient it is to add new documentation to your backend component,

open the demo01-poi-backend component detail view in the RHDH catalog and click the
View TechDocs link in the About tile of the component’s Overview tab. This opens the
current version of the documentation for the backend service.

Figure 6-14: POI backend component Tech Docs.

It’s immediately visible that what you are reading still reflects the documentation as originally
scaffolded during the templating phase of this component. You can fix that right away and

51 Developer Portals: Prepare to Perform with Red Hat Developer Hub

write some useful documentation by clicking the Edit this page icon in the upper right
corner. This brings you to the source code repository, directly into GitLab’s edit mode for the
underlying markdown file of this very documentation page. You might want to use the
exemplary Markdown below or come up with some words on you own:

# POI Backend Component Documentation

The POI backend component represents a web service written in TypeScript with NestJS that
serves points of interest data records from a PostgreSQL database.

Copy and paste this into GitLab’s editor for the docs/index.md file as shown in Figure 6-15
and confirm the change by clicking the Commit changes button.

Figure 6-15: GitLab edit file view for docs/index.md.

This code change will trigger a GitLab CI pipeline run (Figure 6-16), which will generate and
publish the updated documentation. Check the pipeline and give it a few moments to run.

Figure 6-16: GitLab CI pipeline run due to Tech Docs changes.

Once the pipeline successfully finished, switch back to the browser tab showing RHDH
component view. Reload the page in order to see the rendered HTML view with the new
documentation based on the update you just committed.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 52

 Figure 6-17: POI backend component updated Tech Docs.

If you plan to create multiple files, introduce a folder hierarchy for your documentation, or add
images and illustrations, it’s of course recommended that you write the documentation locally
in your Markdown editor or IDE of choice. This allows you to create a separate branch and also
rely on merge requests including reviews for everything you wrote, similar to the workflow that
we used in the Write the code section for implementing the backend component.

Another nice TechDocs feature in RHDH is the possibility to raise documentation related
issues while reading, right from the respective docs page in question. It’s sufficient to mark or
highlight specific words or sentences on the page and wait a bit for a tooltip to appear,
labeled Open new GitLab issue (Figure 6-18).

Figure 6-18: POI backend component open Tech Docs issue.

53 Developer Portals: Prepare to Perform with Red Hat Developer Hub

Clicking it then brings you directly into an issue creation page of GitLab. This page is used by
any readers of the docs to create issues they are facing while trying to make sense of the
existing documentation. It’s pretty intuitive to use; you state the problem right below the The
comment on the text section, as shown in Figure 6-19.

Figure 6-19: GitLab create new Tech Docs issue for the POI backend
component.

Once you are done, click Create issue at the bottom of the page.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 54

 Figure 6-20: GitLab open Tech Docs issue for POI backend.

Switching to the RHDH component view for the demo01-poi-backend component and
selecting the Issues tab, we can of course see this raised documentation-related issue
accordingly.

Figure 6-21: POI backend component Issues tab with open TechDocs issue.

In summary, Red Hat Developer Hub’s TechDocs feature takes away a lot of the usual pain and
hassle related to technical documentation. It is supposed to just work, provided it has been
configured once upfront for RHDH and is properly integrated into the respective Software
Templates.

55 Developer Portals: Prepare to Perform with Red Hat Developer Hub

Update the catalog
After developing the application specific code and writing some documentation, it’s
recommended to also update relevant sections of the catalog-info.yaml for the
demo01-poi-backend component. For this simple service, most of the catalog YAML
definition is fine as originally scaffolded. However, it contains a few general-purpose
descriptions across the contained entities, namely for the Component, the API and the
Resource. Modify the descriptions for the Component, the API, and Resource to something
more meaningful that fits this demo01-poi-backend component. For instance, you may
want to change these as follows:

• Component description: NestJS backend service for the POI Map application.

• API description: API provided by the POI Map application’s NestJS backend service
to load and store POI records from the database.

• Resource description: Database storing the POI records for the POI Map
application’s NestJS backend service.

In order to do that, go to the demo01-poi-backend component’s catalog detail view, select

the Overview tab, and click the Edit Metadata pencil icon in the upper-right corner of the
About tile.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 56

 Figure 6-22: POI backend component Overview tab edit metadata.

This opens the catalog-info.yaml file in GitLab’s edit mode, where you can directly
modify the three descriptions in the YAML definition as shown below:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: demo01-poi-backend
description: NestJS backend service for the POI map application
annotations:
argocd/app-name: demo01-poi-backend-dev
backstage.io/kubernetes-id: demo01-poi-backend
backstage.io/kubernetes-namespace: demo01
backstage.io/techdocs-ref: dir:.
gitlab.com/project-slug: development/demo01-poi-backend
janus-idp.io/tekton-enabled: 'true'
tags:
- nodejs
- nestjs
- book
- example
links:
- url: https://console-openshift-console.apps.cluster-
nxfzm.sandbox2909.opentlc.com/dev-pipelines/ns/demo01/
title: Pipelines
icon: web

57 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 - url: https://console-openshift-console.apps.cluster-
nxfzm.sandbox2909.opentlc.com/k8s/ns/demo01/deployments/demo01-poi-backend
title: Deployment
icon: web
- url:
https://devspaces.apps.cluster-nxfzm.sandbox2909.opentlc.com/#https://gitlab-
gitlab.apps.cluster-nxfzm.sandbox2909.opentlc.com/development/demo01-poi-backend?
che-editor=che-incubator/che-code/latest&devfilePath=.devfile-vscode.yaml
title: OpenShift Dev Spaces
icon: web
spec:
type: service
lifecycle: production
owner: "user:default/user1"
system: idp-system-demo01
providesApis:
- demo01-poi-backend-api
dependsOn:
- resource:default/demo01-poi-backend-db
---
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
name: idp-system-demo01
tags:
- rhdh
- book
spec:
owner: "user:default/user1"
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
name: demo01-poi-backend-api
description: API provided by the NestJS backend service of the POI map
application to load and store POI records from the database
links:
- url: http://demo01-poi-backend-demo01.apps.cluster-
nxfzm.sandbox2909.opentlc.com/swagger
title: Swagger UI
icon: web

Developer Portals: Prepare to Perform with Red Hat Developer Hub 58

 - url:
https://gitlab-gitlab.apps.cluster-nxfzm.sandbox2909.opentlc.com/development/
demo01-poi-backend/-/blob/main/openapi.yaml
title: API Spec
icon: code
spec:
type: openapi
lifecycle: production
owner: "user:default/user1"
system: idp-system-demo01
definition:
$text: ./openapi.yaml
---
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
name: demo01-poi-backend-db
description: database storing the POI records for the NestJS backend service of
the POI map application
spec:
type: database
owner: "user:default/user1"
system: idp-system-demo01

Confirm these metadata changes by clicking Commit changes at the bottom (Figure 6-23).

If you now go back to RHDH into the demo01-poi-backend component’s detail view, select
the Overview tab, and take a look at the About tile, it might still show the previous
component description. The reason is that RHDH, based on configuration settings, will
periodically refresh such component changes by syncing the respective files from the GitLab
repository into the Software Catalog. In case you are impatient, you can click the Sync icon in
the upper-right corner of the About tile to actively schedule a refresh (Figure 6-24).

59 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 6-23: GitLab edit file view for catalog-info.yaml of POI
backend component.

Figure 6-24: POI backend component Overview tab schedule

entity refresh.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 60

Eventually—whether you just waited for a while or actively scheduled a refresh—you will see
the three description changes that have been done in the underlying catalog-info.yaml
in the respective RHDH Catalog view and Component tabs (see Figures 6-25, 6-26, and 6-
27).

Figure 6-25: POI backend component description.

Figure 6-26: POI backend API description.

61 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 6-27: POI backend DB resource
description.

Similar to these basic changes, more complex modifications can be performed whenever
needed, such that the underlying metadata always reflects the current state based on your
most recent engineering activities.

This concludes your RHDH journey for building the NestJS backend service of the POI map
application based on the template you applied earlier (see Backend Templates).

Next up, you will shift focus towards the proxy and frontend code base that has already been
scaffolded (see Proxy and Frontend Templates) into a monorepo using the quarkus-with-
angular template.

Implement the proxy and the frontend

Remember that the quarkus-with-angular template you applied in one of the previous
sections also scaffolded the monorepo, which hosts both the proxy service (Quarkus) and the
Angular SPA (frontend). In this section, you are going to add the necessary application code
for the proxy service as well as the Angular SPA frontend to change the currently present
“hello world” kind of code bases for each of the two applications.

Write the code

In RHDH, switch to the Catalog View and select the demo01-poi-map-service
component. In contrast to the local development workflow that you followed for the backend

Developer Portals: Prepare to Perform with Red Hat Developer Hub 62

service, you are taking a different approach here. In the component’s details view, select the
Overview tab and click on OpenShift Dev Spaces link in the About tile. This will launch a
web-based developer workspace powered by Eclipse Che.

Note: During the time it takes to launch your browser-based VS Code instance, you
might be asked for a re-authentication along the way, potentially more than once
depending on how your RHDH environment has been configured in that regard.

Figure 6-28: OpenShift Dev Spaces login with

OpenShift.

Figure 6-29: OpenShift Dev Spaces authentication

realm account sign in.

Figure 6-30: Dev Spaces log in with Red Hat's single

sign-on technology.

63 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 6-31: Dev Spaces authorize access to grant
full user permissions.

Figure 6-32: GitLab authorize

OpenShift Dev Spaces.

What’s really convenient when taking this route is that you eventually end up in your dedicated
and fully-fledged VS Code instance with the proper Git repository already checked out. This
means you can start right away with coding the application in question—all without going
through any hassle of having to set up everything locally.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 64

 Figure 6-33: OpenShift Dev Spaces welcome screen.
Again, to speed things up, we provide a turn-key ready implementation for the POI proxy
service in a ZIP archive.

In OpenShift Dev Spaces, your web VS Code instance, open a terminal session by selecting
Terminal > New Terminal from the burger menu in the upper-left corner of the UI (see
Figure 6-34).

Figure 6-34: OpenShift Dev Spaces

VS Code open new terminal.

Click into the terminal window at the bottom right of the screen and proceed with the
following steps in order to add the pre-created code necessary for the proxy and frontend
applications to work together:

1. Switch to the parent directory of the current project root folder by typing: cd ..

65 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 2. You should be in a folder called projects. Inside that folder, download the ZIP archive
app-sources.zip containing the finished application sources using: wget …

3. Unzip the archive: unzip app-sources.zip -d app-sources/

4. Copy all the contents from the app-sources folder into the application’s source code
root folder and overwrite all existing files by running: cp -rf app-sources/*
demo01-poi-map/

5. Create a new branch in VS Code by switching to the Source Control view and then
clicking the 3 dots menu (...) in the upper-right of the left view pane. Select Branch --
> Create Branch and use app-dev as the branch’s name.

Figure 6-36: OpenShift Dev Spaces VS Code

name branch.
Figure 6-35: OpenShift Dev Spaces VS Code create
new branch.
6. Stage and commit all changes which are reflected due to copying the final sources
from the unzipped archive into the project’s root folder.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 66

 Figure 6-37: OpenShift
Dev Spaces VS Code
changeset view.
7. Finally, click the Publish Branch button to push this branch to the underlying GitLab
repository.

Figure 6-38: OpenShift Dev Spaces

VS Code publish branch.
8. Open the GitLab repository for the demo01-poi-map component and create a new
merge request for this app-dev branch.

67 Developer Portals: Prepare to Perform with Red Hat Developer Hub

 Figure 6-39: GitLab create merge request for pushed branch.

Figure 6-40: GitLab open merge request for pushed

branch.

9. Merge this new app-dev branch into the main branch right away.

Figure 6-41: GitLab merged merge request for branch

app-dev.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 68

Check CI/CD
The merged code will trigger the pre-configured build pipeline via a webhook. After about two
to three minutes, your code changes are available in the freshly built container image for the
POI map service, which contains both the Quarkus proxy service and the Angular SPA
frontend.

Figure 6-42: POI frontend’s Tekton build pipeline triggered after

merging code changes.
Check POI frontend app status
With the necessary application changes being done, let’s figure out if your POI map proxy and
frontend are running correctly. Open the demo01-poi-map-service in the RHDH catalog
component view, switch to the Topology tab, click on the deployment, and select Resources
from the right-side pane.

Figure 6-43: POI frontend component Topology tab deployment

resources.

69 Developer Portals: Prepare to Perform with Red Hat Developer Hub

The pod seems to be running fine. Explore its logs by clicking View Logs next to the running
pod information. You should see a log output similar to the one in Figure 6-44.

Figure 6-44: POI frontend component pod logs view.

This indicates that the proxy and frontend are up and running fine. After closing the logs, you
can click on the Routes link to open a new browser tab where you should see the POI map
application (see Figure 6-45).

Figure 6-45: POI map application fully working.

Add POI Map application documentation

Backstage promotes technical documentation to first class. Making it relatively easy to create
docs encourages their actual creation. Open demo01-poi-map-service in the catalog.
Click on View TechDocs in the About tile in the component overview. Once again, the
Template scaffolder has left you a bit of boilerplate to start from.

Similarly to the quick edit you made to the backend component (demo01-poi-backend)
earlier, you can perform small-ish updates to the documentation by changing the Markdown
file right in GitLab’s file edit mode. For bigger documentation enhancements, you might want
to work in a clone of the demo01-poi-map-service repo and in the editor or IDE you
prefer.

Developer Portals: Prepare to Perform with Red Hat Developer Hub 70

Update the Software Catalog
After writing the code and the documentation, it’s necessary to update relevant sections of
the catalog-info.yaml files for both catalog components, demo01-poi-map-service
and demo01-poi-map-frontend, so that they match the recent changes and are also
tailored to reflect the POI map application rather than the “hello world” code bases that were
originally generated by the template. You’ve already learned how this is done while working on
the backend component demo01-poi-backend (see Update the Catalog).

Summary
This pilot episode is a cliffhanger. You have seen a developer portal streamline your path to
new application scaffolding and your map app’s basic implementation. You’ve already got
running code.

Usually at about this point in a story we have to introduce a little conflict to hold the reader’s—
I mean hero’s—interest. “Into a little life every rain must surely fall.” (That’s called
foreshadowing. We learned that from Edgar Allen Poe. And Randy Newman.)

Join us next time—when Developer Portals: Preparing to Perform with Red Hat Developer Hub
is published in full.

Additional resources
Visit the Red Hat Developer Hub product page to learn more:
https://developers.redhat.com/rhdh

71 Developer Portals: Prepare to Perform with Red Hat Developer Hub

About the authors

Joshua Wood is a Principal Developer Advocate at Red Hat. Co-author of Kubernetes

Operators (O’Reilly, 2020) and OpenShift for Developers, 2nd Edition (O’Reilly, 2021), he was
formerly responsible for documentation at CoreOS. Wood has worked in roles from sysadmin
to CTO to build utility computing with open source software. He likes fast cars, slow boats,
and short autobiographies.

Hans-Peter Grahsl is a Red Hat Developer Advocate and open source enthusiast who loves
helping developer communities improve their productivity. He is passionate about event-
driven architectures, distributed stream processing, and data engineering. Grahsl lives with his
family in Graz, Austria, and travels often to speak at international developer conferences.

Ryan Jarvinen is a Red Hat Principal Developer Advocate and noted speaker living and
working in Sacramento, California. Jarvinen enjoys learning about best practices for
developer experience and usability in the Cloud Native ecosystem, and helping teams develop
strategies for maximizing collaboration using open source technologies.