Build a service catalog for your software system using Backstage
Tags: architecture, tutorial, productivity, devops
Published: 2022-03-30 19:40:15

## Problem

A software system often contains multiple components such as backend services, database, API, documentation, etc. Is usually hard for us to have an overview, such as how many components we have? which component is connected to which? Who is the owner? Where can I find the documentation? Where can I see the API? etc.
One way to solve this problem is to build a catalog for our infrastructure. We can achieve this quickly with the help of [Backstage](https://backstage.io/).

## What is Backstage?

[Backstage](https://backstage.io/) is an open source project launched by a team at Spotify and is currently a [CNCF Incubation project](https://www.cncf.io/blog/2022/03/15/backstage-project-joins-the-cncf-incubator/). Its purpose is to manage the microservices and infrastructure of the software systems.

Backstage has a Dashboard UI. It uses plugins for different features. Each plugin is presented on a separate page in the Dashboard and has its own URL. So, for example, we can access the catalog plugin using `/catalog` and the documentation plugin using `/docs`.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7u1oi5okiroech2v4p98.png)

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/oujnl4pdafv9q34k3d5r.png)

In the scope of this post, I will demonstrate the use of the catalog plugin. More plugins can be found in the market [here](https://backstage.io/plugins). In addition, I suggest visiting its [Docs page](https://backstage.io/docs/overview/what-is-backstage) for more details on the Backstage project.

## Catalog plugin

The catalog plugin lists all the services, libraries, databases, etc. It also shows the ownership, like who owns what and the relationship between the entities. We can describe this info using YAML files committed together with the code and link these files to the catalog to show them on the UI.

## Let's get our hands dirty.

### Step 1: Installation

Install Backstage using npx:


```
> npx @backstage/create-app
```

Enter `y` to proceed

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jqx4q1a5fxkrzs66xkap.png)

Type in the name of your app:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1dhl4lqvo8cxjjj61abc.png)

Choose database for Backstage backend. Here I choose SQLite just for demonstration. Note that the data will be wiped out whenever we stop the app.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/28g02zcg7fqbnuuf8gm0.png)

After the app is created, we can go to its directory and start it locally with `yarn dev` command.

```
> cd my-system
> yarn dev
```

Backstage runs at localhost:3000 by default. Open the catalog page http://localhost:3000/catalog, and we will see this screen below.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/oujnl4pdafv9q34k3d5r.png)

As you can see, Backstage already includes three services `playback-order`, `searcher`, and `shuffle-api`, just for demonstration. Backstage defines these services in `app-config.yaml` file located in the root directory of the Backstage project code. You can see them at `catalog.locations`. Feel free to remove them if you like. I will just let them there. *insert lazy meme* :))

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zoeg64hxq3pzxy84ad0l.png)

### Step 2: Define our services

We can define our service by writing a YAML file. We should name it `catalog-info.yaml`, as Backstage suggests.

Let's say we have an `order service` written in Node JS. We can define this service like this:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: This service receives new orders and processes them
  tags:
    - nodejs
    - backend
spec:
  type: service
  lifecycle: production
  owner: backend-team
```

Backstage has explained the meanings of all the fields in the file above very clearly in its [documentation](https://backstage.io/docs/features/software-catalog/descriptor-format#contents). Commit this file to your Github order repository.

### Step 3: Add the service to the Backstage catalog

Go to your catalog page at localhost:3000/catalog.
Click on "Create component" -> "Register existing component".
Paste the Github URL to your `catalog-info.yaml` file in the "Repository URL" input field. Then review and tap on import. And we're done!

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qqyh8pei7b9afdw8ja6h.png)

Go back to localhost:3000/catalog. Select the tags nodejs, and we can see our order service is listed there!

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9nu90e0ow8ygkv4yrzul.png)

## Some thoughts

I like the feature of Backstage that allows us to define our infrastructure using YAML files and commit together with the code. This way, we can track the changes in our system by reviewing the commits.

Having everything (backend services, API, docs, resources...) in one place is super helpful. That helps dev teams have an overview and look up the info when necessary.

In my humble opinion, it would be even better to have a feature that automatically discovers our software components instead of manually writing the YAML files, so that the catalog is always up-to-date with the changes of our system.