Welcome to Backstage!
From Spotify, for all developers, with ❤️
Spotify’s Backstage is an open platform for building developer portals written in NodeJS and React. It is open-source, has many features built-in, and is easily extendible with 3rd party or in-house plugins. But what does it contain, how can you develop it and why would you need it?
Main features
Backstage comes with many features ready to be integrated into your existing developer infra. These features are also available to be utilized in many plugins which makes them even more powerful. These core features of Backstage are:
- Software catalog. The software catalog is used to present all your software systems, components, resources, APIs, and their relations to each other. It can also contain information about your company structure in form of users and groups. The catalog is extendible with your own entity types which allows it to model basically any part of your organization be it infra, human relations, physical devices, or anything you can come up with. The software catalog is the base bone of the system as it is used also by other features and plugins.
- Software templates. Software templates are helping by automating usual tasks in your software development cycle. Each template is a simple YAML file containing input parameters for the template and steps to process those parameters. These templates are run by a backend called Scaffolder. Each step is an individual action for example fetching information from a network, saving a file to the filesystem, or creating a git commit or PR. These actions are, surprise surprise, again extendible so you can write your own handlers to match what is needed in your organization.
- Search. Backstage comes with great search functionality that can integrate into search engines like OpenSearch or Lunr. By default, the search indexes are populated based on your Software catalog and TechDocs but it can be extended to allow searching from external services, like StackOverflow or your organization intranet. A lot of the Backstage plugins also integrate with the search functionality making it maybe the most powerful feature of Backstage. As many developers know, finding information can sometimes be very cumbersome.
- TechDocs. TechDocs gives your developers the possibility to write their documentation directly to be part of the codebase and makes them visible in Backstage. The documentation will come visible in the software catalog and is always up to date, or, at least as long as your developers remember to update it as part of their day-to-day programming tasks. And it integrates with the Search giving your developers the possibility to find the documentation they need.
Backstage comes also with ready to use integrations to multiple different systems like AWS S3, Azure, BitBucket, Gerrit, GitHub, GitLab, LDAP, and so on. These integrations can be used for example to populate data to the software catalog. The list of integrations is growing all the time thanks to a very active open-source community. Also, multiple authentication providers are available out of the box which makes it easy to get access rights of your users correct from the start.
Plugins
As mentioned, Backstage can be extended by plugins provided by the open-source community or by your own organization. The list of currently available plugins is already long and, as the number of integrations, it is continuously growing. Spotify also provides a paid subscription to get some of their own special plugins.
Creating your own plugins is possible and easy with help of good documentation. Plugins are divided into frontend and backend plugins. In frontend you can utilize the existing backend APIs provided to you by the Backstage core features or by other plugins. The same APIs are available for the backend, plus you get easy access to the underlying database with help of KnexJS including support for automatic database migrations and a powerful query builder.
Personally, I have already made two open-source plugins for Backstage (Q&A and Toolbox). Publishing new plugins to the Backstage site requires only a pull request to the Backstage GitHub repository and from experience, I can tell that the maintainers are more than happy to see new features pop up. The community overall seems very healthy and there’s a lot of support for newcomers in Backstage’s Discord channel.
Why would I need a developer portal?
From the developer experience point of view having information available in one place is very handy, especially if you currently have:
- Multiple places where you store documentation about your software
- Many systems that provide information about components, APIs, repositories and other software entities
- Unclear view of the relations between the parts of your software
- Hard time to find people responsible / source code / documentation of some system
- Lots of work when starting new projects / bringing new people to existing projects
Building your own developer portal from scratch is always possible but it will take time. All of the previously mentioned issues can be overcome with a medium effort by utilizing Backstage and the power of open-source and inner-source contributions. And if you don’t want to spend time at all, there are also providers like Roadie who can help you set up a Backstage instance as SaaS. Making your developers happy makes your organization happy.
If you find the concept of a developer portal interesting, please go ahead and read more about Backstage on their website https://backstage.io/
About me
I am Heikki Hellgren, Lead Developer, and technology enthusiast working at OP Financial Group. My interests are in software construction, tools, automatic testing, and continuous improvement. You can follow me on Medium and Twitter and check out my website for more information.
