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 Portal​

To create new components through Portal, you first need to set up a software template using the Scaffolder .

If you already have pre-made templates, follow these steps:

  1. Select the Template: Choose the template you wish to create the component from. screenshot of selecting a template for creating new component

  2. Add Metadata: Create a name for your new component and select the group that will own the component from the list. screenshot of adding metadata to a new component

  3. Add Component Location: Choose your host, the organization that owns the repository, and specify a repository name for your new repository. screenshot of adding location to a new component

  4. Review New Component Details: Review the details of your new component. If everything looks correct, click the "Create" button.

  5. New Component Is Being Created: A progress bar will appear. Once it is complete, you will be able to find and view your new component in the catalog. If you encountered any error or you would like to follow the progress, you can see the logs of the process by selecting 'show logs'

Tips to Ensure Success:

  1. Ensure your user has write access to the repository where you are adding the new component.
  2. Make sure your template does not contain a catalog-info.yaml file.

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