The Power of Customization: Making Backstage Work for You with Roadie

Backstage is the most flexible way to build an Internal Developer Portal that exists. The downside of this flexibility is that it can take a lot of effort to use. Roadie’s mission is to take the hassle out of Backstage, but we want to deliver on this goal without preventing our users from customizing Backstage to the fullest extent possible.

This article explains many of the customization options available in Roadie today. From look-and-feel customization like theming, to deep data model flexibility, custom scaffolder actions, and completely custom plugins, Roadie has the flexibility you need.

Backstage customizability

Backstage is not a Developer Portal. It’s actually a framework for building developer portals. You can think of it as being more like a Software Development Kit for building your own developer portal. Each company is expected to mix & match and extend the libraries that the Backstage community make available, so that they end up with a completely customized and unique IDP.

This fact is evident from day one of using Backstage. To get started, you don’t download and run a Docker container like you might expect. Instead, you run a command line tool to scaffold your own Backstage instance. Once that’s done, you write your own code to customize it.

-> npx @backstage/create-app@latest
? Enter a name for the app [required]: acme-corp-idp

Creating the app....

Another example of this flexibility is evident in the plugin architecture. The Backstage community has created hundreds of open-source plugins that can be installed into a Backstage-based IDP in order to provide visibility into the many many tools that might be used. Backstage is designed in a way that makes these plugins easy to install and configure.

From authentication hook points to source code management tool integrations to self-service scaffolder templates and UI components…. each and every part of Backstage can be ripped out and replaced and customized to your needs and desires. This is part of the philosophy of Backstage.

Roadie customizability

Despite being built on Backstage, Roadie is a complete, out-of-the-box, developer portal. We take away all of the work of building and maintaining your IDP, so that you can focus on getting value from the tool.

We believe that most organizations shouldn’t need to build a team of 4 or 5 engineers around Backstage. You should want most of your engineering efforts focussed on initiatives that deliver direct customer value, rather than building internal tools from scratch.

This is one of the reasons Roadie is delivered as Software as a Service. We want you to show up on day one and just start using it.

At the same time, we also want to retain the philosophy of Backstage. You need to be able to customize Roadie just as much as you would customize Backstage. You should to be able to connect your own authentication providers, integrate your homegrown tools, and mix and match the plugins that make sense to you. For this reason, we strive to make Roadie as customizable and extensible as we possibly can.

We believe that by combining Roadie’s ease of use with the flexibility and scope of the Backstage ecosystem, Roadie offers the best of both worlds, and is the best IDP on the market.

This post explores many of the major ways you can customize Roadie to meet your needs. Here are your options.

Theming and UI

Your IDP should look and feel familiar to your users, and it should focus their workflows in order to improve efficiency.

Logos and branding

Roadie let’s you replace the logos and branding across the site so that you can expose an IDP that matches your brand and themes.

This image shows the dark-mode version of a theme for a fictional company called BeautyBox.

Sidebar

Roadie’s sidebar configuration lets you cut the navigation down to focus it on the most important use cases in your company. If you don’t need self-service automation capabilities in your IDP then you can easily remove them to streamline things.

We also support reordering of sidebar sections, custom plugins in the sidebar, and deep links to important documentation.

Catalog customization

The Roadie catalog offers control over how the catalog is collected in the first place, and how it is represented to end users who need to consume information in the catalog.

Data model

Many engineering organizations have custom terminologies they use to describe their particular software development life cycle. If your company uses Domain Driven Design, you might want top level concepts like “Value Streams” in your catalog. Other companies might want to support groups of people called “Tribes”. Probably every company will want a list of “Products”.

Roadie supports a flexible and customizable data model that lets you rename existing Kinds and create your own types of entities.

The screenshot below shows:

1. Backstage’s Group kind renamed to “Teams”,
2. A custom entity type called “Products” has been created,
3. Unused kinds like Locations and Domains have been hidden from users.

Table columns

Different IDP users have different jobs, and that means they need different views. Roadie’s tables can be customized on a per user basis, so that everyone can streamline the UI to match the workflows they need.

Users can turn columns on and off, resize columns and change the density of catalog tables. The best part is that these settings are persisted so you can easily dive back into your workflow.

The launch announcement covered the benefits of Roadie’s catalog UI in more depth.

Entity providers

Custom entity providers are a way to provide entities into the catalog from external systems and existing data sources. They’re a critical integration point that helps ensure that your catalog will automatically stay up to date with external systems.

Roadie makes it easy to use custom entity providers via the Roadie Agent. The agent is a library that you can dump entities into in order to have them appear in the catalog.

Here’s a simple example where we use the Roadie Agent to dump an array of hardcoded entity metadata.

const { RoadieAgent, createRoadieAgentEntityProvider } = require('@roadiehq/roadie-agent');

const fakePayload = {
  type: 'full',
  entities: [
    {
      entity: {
        // Standard Backstage entity metadata omitted for brevity
      },
    },
  ],
};

const myEntityProviderHandler = async (emit) => {
  await emit(fakePayload);
}

RoadieAgent.fromConfig()
  .addEntityProvider(
    createRoadieAgentEntityProvider({
      name: 'testprovider',
      handler: myEntityProviderHandler
    }),
  )
  .start();

Auto-discovery settings

Any software metadata in YAML files should be auto-discovered by Roadie so that engineers don’t need to remember to register it via the UI.

Roadie supports custom auto-discovery settings, including glob matching.

Group and User ingestion

Roadie needs an organization chart in order to ensure that ownership of software can correctly be assigned to teams (aka. Groups), and to ensure that scorecard data is correctly rolled up through the org chart.

The best way to make sure the org chart is up-to-date and correct is to automatically sync it from a HR tool. To facilitate this, Roadie supports built in integrations for Microsoft Graph (also known as Microsoft Entry ID, or Azure Active Directory) and Okta. Other solutions can easily push Users and Groups into the catalog via our API.

Plugins

The real power of the Backstage ecosystem comes from its plugins. Roadie supports more than 70 Backstage plugins out of the box at the time of writing (September 2024). It typically takes us about a day to integrate a new open source plugin once it’s created by the community.

Plugin configuration

Most plugins have configuration options that Roadie admins need to be able to configure to suit their particular setup. This is easily done via admin panels we have built into the product.

Take the Argo CD plugin for example. Roadie supports two completely separate ways of integrating with Argo CD:

1. The app locator method allows you to dynamically search and identify Argo CD registered applications from multiple Argo CD instances.
2. The proxy method is used to construct links to individual Argo CD applications.

You can choose the best one for your needs, and even configure minute details like Namespace and Resource allowlists and blocklists.

The APIs of your Argo CD instances are probably not exposed on the public internet, but it’s still easy for Roadie to access them securely. We provide an open-source broker that runs in your infrastructure and makes an outbound connection to Roadie.

For other plugins, like the Kubernetes plugin and EKS, we support AWS Role Sharing as the preferred configuration method. Whatever your connectivity needs, we probably have a solution for it.

Of course Roadie’s responsibilities don’t begin and end with plugin configuration. We’re also:

1. Vetting plugins for quality issues as we integrate them,
2. Scanning plugins for licensing issues (which your legal team will be happy about),
3. Documenting plugins so people know how to use them,
4. Updating plugins as their authors release new features.

Frontend plugins

If there isn’t a community created plugin that suits your needs, or you need a plugin for a homegrown tool that only exists in your company, Roadie can support that too.

Users can write native Backstage plugins that run on Roadie and securely connect back to your private internal APIs via the broker.

The plugin development workflow supports the ability to locally host custom plugins and run them right on Roadie during development. This basically means that you can make a change to your plugin code in your IDE, and simply refresh Roadie to see your changes live.

We also support running production and development versions of the same custom plugin in Roadie at the same time, so you can iterate on your plugins without disrupting your users.

Productionizing a plugin is as simple as running the Roadie CLI against it to package it up and push it to Roadie.

roadie plugin:build --location /my-custom-plugin-folder/ --host https://static-assets.roadie.so/<my-tenant>/myCustomPlugin

The full range of Backstage frontend APIs are available to your custom plugins. You can query the catalog, check Role Based Access Control permissions, and even push analytics to see how people are using your plugin.

Proxies

Plugins frequently make use of proxies to upgrade requests with token authentication before forwarding them on to a backend service to retrieve data. Roadie users can create their own proxies inside the application. These proxies can be used to connect to third-party SaaS APIs like PagerDuty, or private internal APIs.

Here’s a user created proxy for SonarCloud.

Entity Pages

Entity pages are the pages in the catalog which pull together information on a particular piece of software, a team, or an infrastructure resource.

UI layouts

Adding plugins to Roadie interfaces is a simple matter of picking them off a list. This process is the same for both community created plugins (including plugins created by Roadie, plugins created by Spotify, and official plugins from companies like PagerDuty and Snyk) and for custom plugins you create yourself.

Once you’ve chosen your plugin, simply drag-and-drop it on the page, and resize it to suit your needs.

Different types of entities need different layouts. The Backstage Lighthouse plugin makes sense for a website, but not for a Kubernetes cluster. Roadie organizes the plugins in this way so that it’s easy to create custom views without too much setup. Our built in role based access control ensures that admins have the power to set up layouts, without overloading regular users with too many options. Team pages are customizable in the same way, they just typically have different cards and widgets.

Props on plugins

Sometimes individual cards will have their own editable properties. Roadie supports that too. For example, this card displays a list of recent GitHub Actions CI runs and their status. But how many recent CI runs should be displayed, and what layout should be used? Well, you can set that with the editable props.

This screenshot shows the edit mode of the Dynatrace Backstage plugin.

Metadata cards

We’re aware that many platform teams wish to display custom information in Roadie, but don’t necessarily have the TypeScript skills on hand to create custom plugins from scratch. To make this easier, Roadie includes no-code cards that can display information from custom metadata on the Entity.

Imagine we have a Backstage entity with some custom properties in its metadata.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sample-service
spec:
  type: service
  owner: group:roadiehq/engineering
  lifecycle: production
  custom:
    engineeringManager: user:dtuite
    productManager: user:samnixon87

How would we display this in the catalog? On Roadie, it’s as simple as adding the EntityMetadataCard and configuring it in a couple of clicks. The card even auto-links the Engineering Manager and Product Manager to their User pages in the catalog.

Home page

Of course it’s not just pages in the software catalog that can be customized. Roadie users can also customize the Home page plugin to display key information that’s relevant to them. This is the place to display your open pull requests, community news, your calendar, and other useful info that’s tailored to the logged in user’s experience.

Scaffolder

Roadie scaffolder supports the full range of customization that you would expect from the Backstage scaffolder.

Actions

Custom scaffolder actions are a way to execute homegrown CLI’s or arbitrary code as part of scaffolder templates. These are executed within your own infrastructure, which provides an added benefit in that it makes it easy to send internal network requests.

Users can use the Roadie Agent (the same library used in the Custom Entity Providers section above) to register custom scaffolder actions with Roadie.

RoadieAgent.fromConfig(config)
  .addScaffolderAction(
    createRoadieAgentScaffolderAction({
      name: 'custom-action', // The name of the action as defined in Roadie
      handler: async (ctx) => {
        try {
          fs.writeFileSync(
            `${ctx.workspacePath}/test.txt`,
            'new file with new contents',
          ); 
          // Writing a new file into the shared workspace
        } catch (err) {
          console.error(err);  // Local logging on the Roadie Agent process
        }

        let count = 0;
        while (count < 5) {  // Additional other actions that is wanted to be taken. This time looping for 5 seconds
          await new Promise((resolve) => setTimeout(resolve, 1000));
          count++;
          await ctx.log(`hello world`); // Sending a log message to be displayed to the end user
        } 
      },
    }),
  )
  // Add a second custom scaffolder action
  // .addScaffolderAction(...) 
  .start();

These can then be used in your templates like this:

steps:

  # This step executes on Roadie
  - id: fetchTemplate
    name: Fetch file
    action: fetch:template
    input:
      url: ./skeleton

  # This sends the workspace context to a self-hosted scaffolder runner
  # and executes the custom action we defined above. The payload passes
  # values to the self-hosted scaffolder runner and logs are written
  # back to Roadie.
  - id: invokeCustomAction
    name: Invoke a custom self-hosted action
    action: roadie:agent
    input:
      action: custom-action
      shareWorkspace: true
      payload:
        name: someValue

Field extensions

Custom field extensions give you the ability to build your own inputs and UI components for the scaffolder. You write them using the normal Backstage API, and push them into Roadie using the custom plugins pipeline.

Once registered, they can be used in Scaffolder templates by matching the name of the ui:field prop.

parameters:
  - title: Fill in some steps
    required:
      - name
    properties:
      name:
        title: Name
        type: string
        description: My custom name for the component
        ui:field: MyCustomInput

Authentication & Authorization

Single-Sign-On (SSO) setups

Roadie provides native support for any SSO provider you can imagine. Okta, Microsoft Entra ID, Google, AWS, Ping Identity…. you name it, we’re probably already using it in production.

Setting this up is a simple matter of sending our docs to your IT team, or whoever controls your SSO setup. We will then work directly with that team to get your authentication provider configured.

Once set up, your IT team can grant and revoke access to Roadie without being blocked by us. They have full control over the process.

Roles

Customers who have purchased our role-based access control add-on can define custom roles which can then be assigned to groups of users.

In this example, you can create a role which can only read the catalog. It wouldn’t be able to execute scaffolder templates or register anything in the catalog.

Roles can also be assigned via your Identity Provider like Okta or Microsoft Entra ID. This is especially useful when your IT team wishes to manage access and roles in a single place.

Permissions/policies (coming soon)

When role-based access control gets really powerful is with the ability to define custom permissions which can then be combined in roles. For example, perhaps you want to hide Component entities which are tagged with sensitive from everyone except the security team.

We’re working on this ability at Roadie and expect it to roll out in 2024.

Tech Insights (Scorecards)

Custom data sources

Data Sources are recurring jobs which gather data that can then be used to write checks against.

For example, Roadie comes with a built-in GitHub Settings Data Source which records facts about each repository in the catalog, like whether or not branch protection is turned on, or whether or not force pushes are allowed.

Users can also create their own Data Sources from scratch. At the time of writing, 7 different types of Data Sources are supported. Here are some examples:

1. HTTP Data Sources hit third-party APIs and pick values from the JSON response
2. Component Repository File Data Sources inspect files in the repository associated with each Component and record values from them.
3. Push Based Data Sources receive webhook events and store them for processing.

Creating Data Sources is a simple matter of filling out a few fields. You don’t need to write any TypeScript or YAML. Data Sources support advanced features like metadata variables, JSONata processing, inline testing, and error handling.

Custom checks

Checks inspect a value created by a Data Source and give it a pass or fail for each entity it applies to.

This check ensures there is a README.md in the repository associated with each piece of software.

Advanced features like boolean logic and live testing of the check are supported. Checks can link to documentation when they fail, or even link to a scaffolder template that can help the owner of a service to fix the failure.

Custom scorecards

Users can create their own scorecards that apply to the software in the catalog in order to communicate best practices and expectations to teams.

Each scorecard is a user defined collection of checks that shows up in reporting, in the catalog, and on team pages. Scorecard data is rolled-up through the catalog so that you can dip in at any level of the org chart and see aggregated data from below that point.

And there’s more coming

We’re constantly adding to the ways you can customize Roadie. If you want to stay up to date with the latest customizations, subscribe to our newsletter to hear what’s coming.

Image by GrumpyBeere from Pixabay