Skip to main content

Software Catalog Overview

What is a Software Catalog?​

The Portal Software Catalog is a centralized system that keeps track of ownership and metadata for all the software in your ecosystem (services, websites, libraries, data pipelines, etc). The catalog is built around the concept of metadata YAML files stored together with the code, which are then harvested and visualized in Portal.

How it works​

Portal and the Portal Software Catalog make it easy for one team to manage 10 services — and makes it possible for your company to manage thousands of them.

More specifically, the Software Catalog enables two main use-cases:

  1. Helping teams manage and maintain the software they own. Teams get a uniform view of all their software; services, libraries, websites, ML models — you name it, Portal knows all about it.
  2. Makes all the software in your company, and who owns it, discoverable. No more orphan software hiding in the dark corners of your software ecosystem.

Getting Started​

The Software Catalog is available to browse at /catalog. If you've followed Getting Started with Portal, you should be able to browse the catalog at http://localhost:3000.

screenshot of software catalog homepage

Adding components to the catalog​

The source of truth for the components in your software catalog are metadata YAML files stored in source control (GitHub). Repositories can include one or multiple metadata files. Usually the metadata file is located in the repository root. This is not a formal requirement & metadata files can be placed anywhere in the repository.

There are 3 ways to add components to the catalog:

  1. No-code wizard (Recommended)
  2. Manually register components
  3. Creating new components through Portal

screenshot of no-code catalog wizard

  1. Select your team from the drop-down list
  2. Portal will suggest the software components it thinks your team owns.
  3. You can update the list of components you want to add by
    • Selecting "Add more" and search for other components your team owns
    • Remove the software components you want to remove by selecting the checkboxes and "Remove"
  4. Make sure to select the component type from the drop down for each component
  5. Once you're ready to add the components to the software catalog, you can select "Create pull requests". This will create a pull request with the catalog-info.yaml file that describes each component you add.
  6. Once created, you can view the pull request in Github and share with your team to review before merging.
  7. Once the pull request has merged, it will appear in the software catalog page. This can take up to 3 minutes.

Manually register components​

Users can register new components by going to /catalog-import and clicking the REGISTER EXISTING COMPONENT button:

screenshot of manually register existing component

Backstage expects the full URL to the YAML in your source control. Example:

https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml

More examples can be found here.

It is important to note that any kind of software can be registered in Backstage. Even if the software is not maintained by your company (SaaS offering, for example) it is still useful to create components for tracking ownership.

Creating new components through Backstage​

All software created through the Backstage Software Templates are automatically registered in the catalog.

Static catalog configuration​

In addition to manually registering components, it is also possible to register components through static configuration. For example you can add components through the Config Manager under the Catalog plugin > Locations. For example:

Type: url
Target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml

Updating component metadata​

Teams owning the components are responsible for maintaining the metadata about them, and do so using their normal Git workflow.

screenshot of updating component metadata

Once the change has been merged, Portal will automatically show the updated metadata in the software catalog after a short while.

Finding software in the catalog​

By default the software catalog shows components owned by the team of the logged in user. But you can also switch to All to see all the components across your company's software ecosystem. Basic inline search and column filtering makes it easy to browse a big set of components.

screenshot of finding software in the catalog

Starring components​

For easy and quick access to components you visit frequently, Portal supports starring of components:

screenshot of starred components