Backstage in Production: Considerations for Platform Teams
The developer portal is a prominent aspect of most platforms, as it’s a privileged point of interaction between you and your users. Developer portals reflect the features of the platform through a centralized UI, which means they must be tailored to your developers and the capabilities you want to provide.
Here’s where Backstage shines: customizability. You can make the developer portal of your dreams with Backstage, which could include replacing the UI with your organization’s design system or bringing your own data consumption mechanism. This is possible because Backstage is not a ready-made developer portal, but a framework that provides the building blocks to build one.
However, developer portals are web apps. Thus, when you adopt and extend Backstage from scratch, you’re signing up for its full-stack consequences. For this reason, Gartner and others have reported that setting up and maintaining Backstage yourself can be challenging, yet the value of doing so has overwhelming benefits for many companies.
With that said, there is no one-size-fits-all way to adopt Backstage. When you set out to stand up Backstage yourself, you’ll run into a few common tasks nobody told you were part of adopting the framework. In this article, I’ll walk you through a few considerations to make when planning your team’s work.
Initial Setup and Deployment
Backstage provides a
create-app command through its command line interface (CLI) to help you get started with a new instance. The result will run fine on your machine, but from this point on, you still have some work to do to make it a production-ready developer portal.
My recommendation for a Backstage proof of concept is to implement first a single meaningful integration like GitHub. This will let you go through all the touch points from React and Node configs to deployment.
Your developer portal most likely will have to connect data from various sources through integrations. Therefore you’ll need to implement a secret-management strategy that lets you inject secrets into the container that will be running Backstage.
In terms of deployment, the Backstage team recommends using what you normally would for a similar application. Thus, you can benefit from applying your standard CI/CD practices to your developer portal.
In the case of a Roadie-managed Backstage instance, all these considerations are built into the product so you don’t have to invest time into any of them.
Authentication and Security
Your developer portal is a one-stop shop that integrates third-party services such as GitHub, Argo CD or PagerDuty. The developer portal will allow users to request infrastructure through its self-service or golden paths capabilities. Therefore, it is important to ensure that your Backstage instance is secure.
First, you’ll need to install and set up an authentication mechanism. Thankfully, Backstage offers open source integrations with 13 providers from Okta to Google IAP.
Next, you’ll need to use the permissions framework that comes with Backstage. By default, Backstage’s backend routes are not protected behind authentication because there’s an openness assumption in a developer portal.
Additionally, I recommend you set up your scaffolder to execute tasks in ephemeral environments. Doing this at Roadie from the beginning prevented all of our customers from being affected by last year’s Backstage remote code execution vulnerability.
Always remember to keep an eye on the security patches released by the Backstage teams and upgrade your instance constantly.
Upgrades and Maintenance
The Backstage team merges around 300 pull requests monthly from many contributors, resulting in minor version releases every second week. This process gives the framework an impressive flow of features and bug fixes.
I recommend adding upgrades to your planning regularly. Backstage’s upgrade process currently involves a few manual steps, with varying complexity for each release.
Beware that some improvements come as an additional API that you need to hook into your developer portal or a new set of UI components that can benefit your instance.
Most importantly, it’s useful to stay tuned to new features as sometimes you have to opt into them even after you upgrade Backstage. I write the Backstage Weekly newsletter, so you don’t have to go through the codebase yourself. Feel free to sign up.
Working with Plugins
There are more than 100 plugins available in the Backstage ecosystem, and you’re encouraged to build your own plugin to integrate your unique development needs into Backstage.
Plugins are usually implemented in two or three packages: backend, frontend and common. Plugins can also provide extension points, so they can be customized or adapted for different circumstances.
The Backstage community is actively working on simplifying the process of installing and upgrading plugins, but it remains a bit of manual work at the moment and requires you to redeploy your instance.
When authoring a plugin, be aware that Backstage is consolidating a new backend system with simplified APIs, so might be worth checking it out.
A Backstage Instance Is Just the First Step
Or maybe it’s the second step? You first need to identify what you want your developer portal to solve. Then once you set up an instance, you’ll be on track to a longer-term journey onboarding more use cases and iterating on your developer portal as you learn from your developers.
If you want to adopt Backstage but don’t want to own its implementation or maintenance, Roadie.io offers hosted and managed Backstage instances. Roadie offers a no-code Backstage experience and more refined features while remaining fully compatible with the open source software framework. Additionally, Roadie offers fully-fledged Scorecards to measure the software quality and maturity across your organization.
If you’re interested in learning about the advantages and trade-offs of managed production-grade Backstage instances vs. self-hosted ones, check out our white paper.