Here’s what you actually want: your developers waking up, drinking a cup of coffee, then getting into a flow and spending their day building new features or solving hard business problems.

And here’s what you really don’t want: your developers waking up, drinking a cup of coffee, then chasing your other developers in order to figure out who owns the service that just broke this other service, only to discover it was maintained by someone who doesn’t work here anymore, but wait, someone finally found documentation for it, except never mind, the docs have never been updated, and oh yeah, the whole thing was written in Ruby even though everyone else has been using Node except for that one dude who won’t give up on Perl. Aaargh.

Although the example above may seem like an extreme case, there’s a little bit of all that — unclear ownership, poor discoverability, subpar documentation, unclear tech standards — dragging your development teams down bit by bit, minute by minute, all day, every day. And whatever is holding your development teams back is also holding your company back.

The specific harms to developer experience are varied and go by many names: context switching, cognitive load, fragmentation, silos, duplication, toil, dependencies, congestion, more dependencies, changing priorities, tech debt, bad coffee, and other things that keep platform engineers up at night.

These problems are more acute if you’re a company with a growing engineering org. Maybe you just acquired another company. Maybe you just moved everything to the cloud. Maybe it’s not how big you are, but how fast your org is expanding or how fast your tech stack is changing. Regardless of what business or industry your company is in, if you keep building, eventually the chaos comes knocking. And with the rapid, widespread adoption of generative AI code creation tools, this software sprawl is only accelerating.

So, what’s the solution? An internal developer portal (aka, an IDP*), of course!

Or at least, that’s what you read or heard somewhere — in an article on The New Stack or at a DevOps conference — and that’s how you found yourself here. But can the same solution really address all these different problems?

The easy answer is, yes, a portal can do a lot — that’s the amazing thing about internal developer portals. Their job is to take the vast, complicated web of your internal software and infrastructure — all your custom services, websites, libraries, data, docs, standards, and processes, plus all your internal and third-party tools and frameworks — and abstract that tangle into a seamless, cohesive, centralized whole that your developers can actually make sense of.

So instead of bookmarking tab after tab after tab — for every software component times every software tool — one for the CI/CD, one for the cloud provider’s console, and one (or two or three) for wherever you hunt for technical documentation — now your developers go to one place: Backstage. A single pane of glass for all your infrastructure.

But that’s the easy answer. The difficult answer is actually another question: if a portal can do so much, where do you even begin?

There are a few core features that every internal developer portal should start with. One of those features is a catalog. The Backstage Software Catalog is like a services catalog — except instead of just services, it includes any kind of software component your teams have built: services, web apps, libraries, data pipelines, you name it.

Having information about all your components centralized in Backstage promotes both discoverability, ownership, and quality. What is this thing? Who owns it? How does it work? And is it healthy? Making it so anyone easily finds the answers to these questions when they want and when they should — on their own, at any time — is one of the simple joys of Backstage. Owners can easily manage the stuff they build and maintain. Users can find owners and understand dependencies. Teams can discover and reuse existing components instead of rebuilding them. And everyone can shout a little less in Slack.

Each entity in the catalog also gets its own page where anyone can see its deployments, docs, APIs, and more. Metadata (like ownership and lifecycle) from the catalog can be shared with other parts of Backstage, as well. And that’s just the beginning of what happens when you bring order to your tech ecosystem with Backstage.

Can templates be magical? One of the central beliefs in Spotify’s engineering handbook is: “The fewer technologies we are world class on, the faster and more effective we get.” In other words, if we all use the same Java framework for building our backend services, now we have an org full of experts in that Java framework. So if you have to troubleshoot or take ownership of someone else’s backend service, you don’t have to learn how they built it, because more often than not, it’s how you would have built it.

But no one starts out as an expert in something, and everyone likes to build their own way, the way they’re used to. So how do you get people to align around the same tech standards? By making the right way to build something, the easiest way. That’s where Backstage Software Templates come in.

You configure your ideal way for how to build a service (or website or data pipeline, etc.) in a simple YAML file, and the Backstage Scaffolder creates a software template based on that Golden Path. Now all a developer has to do is go to Backstage, select the template, fill in a few form fields, and voilá — a new repo in GitHub Enterprise is created with a Hello World project using your preferred languages and frameworks, the first build is already running through your CI/CD, and, if needed, fully set up for observability and scalability. And the developer never even left Backstage.

Beyond the catalog and software templates, the idea of an internal developer portal is to provide a single UX for all your software and infrastructure, from managing deployments to security alerting, to graphing dependencies, to whatever you can imagine. Because the framework is extensible via plugins, you can add any feature you want to your portal, customized to your tech stack.

Using Snyk for security alerting? Add their official Backstage plugin. Using PagerDuty for managing incidents? They have a Backstage plugin, too. Need to do that one thing no one else does because you inherited some legacy system that still needs support? It’s easy to build your own plugin for it.

Plugins are the building blocks of functionality in Backstage. (In fact, the Software Catalog and Software Templates are also plugins.) There are plugins that automatically create great-looking documentation sites from Markdown files, help you manage your Kubernetes deployments without having to be an expert in clusters, and more. At Spotify, we use over 120 plugins in Backstage to do everything from ensuring quality standards of our software components to helping us run our internal Hack Weeks.

Simple! Backstage plugins integrate all the different parts of your existing infrastructure on the backend in order to provide a unified UX for your teams on the frontend.

Extensible! As you learn more about Backstage, you might find yourself constantly wondering, “It can do that, too?” Yes, it can. That’s the power of an extensible, open platform with a plugin architecture — it evolves as your infrastructure evolves. (That’s also what makes it confusing for people new to Backstage. It can do all the things!)

Take a deeper look into how Backstage works in our product docs.

The Backstage framework is based on Spotify’s homegrown developer portal, which we built in-house and developed internally for years during a period of fast-paced growth for the company. We were gaining new listeners and new developers quickly, and we were also making the transition to the cloud and adopting a microservices architecture.

While all this growth and change was great and exciting, it also started to produce sprawl and confusion. With thousands of R&D members and tens of thousands of software components, no one could find anything or anyone. It was getting more difficult to onboard new developers and our existing devs were getting crankier, too. This was more than tech debt catching up with us. This was complexity inherent to our scale. We were still getting bigger, but now we were also getting slower.

What’s more, we had a unique organizational model built on empowering hundreds of small, cross-functional squads. That meant we required a unique solution — one rooted in developer experience.

We started simple, with a services catalog. Then we introduced TechDocs and Software Templates. By 2018, we had the first internal version of Backstage. As our developers found our new portal more valuable, they invested in it more — both using it more and building more plugins for it. It kept growing and improving until eventually everyone in our internal R&D community was using some part of Backstage to do their job every day.

Unlike other enterprise software, Backstage was not conceived with a corporate business plan in mind. It was built by developers for their fellow developers — with all the empathy, trust, and scrutiny that entails. (You think K-pop fans are tough to please? You haven’t met our data scientists.) Our portal was built on feedback (lots and lots of feedback, years of feedback) from teams using it for production use cases on a daily basis. This is the sort of real-world product discovery that simply can't be replicated outside of a few of the world’s top product development companies.

Because it’s an internal platform, features live or die by whether they prove useful to the people who depend on them every single day to get their work done. Our customers, then and now, are other Spotify technologists: backend engineers, web devs, data scientists, data engineers, ML/AI engineers, PMs, EMs, and other very technical, very particular people. But now our customer base also includes the R&D community outside of Spotify, product teams working at companies as different from streaming music as making cars and international banking.

Our homegrown portal was working so well for us, we thought other companies would find it valuable, too. In 2020, we open sourced the framework, so that any company could build a Backstage developer portal of their own.

We decided to release the framework as a free open source project, because we believe the Backstage platform — and critically, our own internal Backstage instance — benefits from having as many people and companies supporting and contributing to it as possible. Through this platform, we’ve built a worldwide community of nerds focused on improving developer experience, and we couldn’t be happier about it.

When we donated the project to the CNCF (Cloud Native Computing Foundation) — the home to Kubernetes, Envoy, and other pivotal open source technologies — our hope was that Backstage would become the industry standard for internal developer portals. Today, there are over 2,600 companies who have adopted Backstage. And the ecosystem of third-party plugins, add-ons, and other services continues to grow as the community grows.

We hope you can join us and be a part of it.

Want to learn more about Backstage? Talk to us during our Office Hours.