Internal Developer Portals — Backstage vs Port: Part 1

Dillon Courts
Published in
8 min readApr 16, 2024

An internal developer portal (IDP) is a central location developers, teams, and managers use to assist in the development and maintenance of software. It is a one stop shop to view ownership of specific services, technical documentation, observability metrics, deployment statuses, and more. The goal of internal developer portals is to solve for the following:

  • Developers need to learn and interact with too many tools
  • Too much context switching
  • Too much time spent finding technical information
  • Not enough self service operations available to developers
  • Lack of clear ownership of services

The term internal developer portal is often used interchangeably with developer platform. However, these are not the same thing. A developer portal is a single pane of glass for software management, a developer platform is the entire ecosystem of tools a developer uses to develop, deploy, and maintain software. A developer platform may be extremely sophisticated and managed by an internal team, allowing for one click deployments and rollbacks, and abstracting away the complexities of infrastructure like kubernetes or continuous deployment tools like ArgoCD. Or it may be a collection of established patterns for Infrastructure as Code, where developers own and maintain their own CI/CD scripts and infrastructure creation. Different organizations may opt for different approaches. Traditionally I have seen smaller companies placing larger burdens on their development teams, asking them to know more about how their applications are built, deployed, and run in production with less abstractions. Larger companies often dedicate a team or teams to this functionality, in theory allowing their development teams to focus purely on development. I have my own thoughts on that which warrant its own future blog post.

The Scenario

I had been buried in client work the last couple years and emerged to discover I had totally missed the internal developer portal trend that seemed to be the talk of the town in platform engineering circles. I wanted to familiarize myself with some of the top offerings in the space so I chose to explore Backstage and Port.

Before we dive into the proof of concepts I did with these projects let’s define what an internal developer portal is, and what problems it is supposed to solve.

Setting the Scope for a Proof of Concept

I wanted to test the following capabilities of IDPs.

  • Software Catalog
  • TechDocs
  • Scorecard Concept
  • Software Templates
  • CI/CD Integration
  • Single Pane of Glass Portal

To do this I utilized Google’s microservices-demo to create separate repositories for each microservice in the demo as the existing repository is set up as a mono repo. While both backstage and port do support mono repos, I wanted to test a more traditional approach that I see at most of my clients in regards to microservices and repository structure.

I’ll cover the first 2 capabilities in this blog post, Software Catalog and Tech Docs. I will cover the other concepts in a future post.

Getting Started


The backstage getting started docs got me up and running with a local backstage instance within an hour or two. It introduced me to a few of the core concepts and walked me through connecting to my personal github account, which could be substituted for an organization quite easily. There were some app configuration steps I could take to customize the look and feel of the app but I skipped those as I’m more interested in the functionality at the moment. Ultimately the getting started felt a bit shallow and didn’t take me much further than setting up a local backstage instance and walking me through how to import an existing component into the software catalog. I had to dig much deeper to explore the other capabilities I had set out to evaluate.


The port getting started docs were pretty bare as well but I think this worked out better for Port than it did for backstage. Port let their application do the explaining and showed off the ability to customize the home page by putting instructions for next steps in a markdown generated window right on my landing page after sign up. In addition to the next steps instruction was an embedded video giving me an overview of port. This seemed powerful and I was eager to see what I could do here. Could I add observability dashboards on this page?

Another thing port did that I neglected to get a screenshot of was sync with my github account and automatically import all of my repos into its service catalog. I allowed this to happen and ended up deleting some of them later as I didn’t want everything in my catalog. I still thought this was a neat feature.

From here I was on my own and set off trying to register a new component in the software catalog.

Registering a component in the software catalog


This was pretty straight forward, only requiring me to enter the url to my repository. Backstage opened a pull request for me to set up a basic backstage config file in the repo that I can fill in with details about the service later. I thought that was a pretty nice feature.

My component was then available in the catalog.

I will admit that I spent about a half an hour trying to figure out how to create a group so that I could assign ownership of the service to someone other than guest. After clicking through the portal everywhere I could think of it finally clicked for me that backstage is built on configuration. I located in my local example backstage source code where the existing guest group was defined and added a new entity with my new group name. The app auto reloaded and my group was immediately available! Pretty cool, I was starting to see how a platform team could maintain their own configuration for their backstage instance in a separate repository. Backstage even has the capability to import groups from your auth provider, including github teams, but I’m not going to cover that here.


This was straight forward, I went to the catalog page, clicked services, and clicked the + Service button.

If I had noticed I could scroll down in my services list, I would have seen that port picked up the new service automatically when it was added to my personal github account about a half hour earlier. So there was no need for me to add it manually since I had followed the initial onboarding process of syncing my github account.

I did not run into the group creation with port, it was very simple to click the users icon and click the button to create a team. This immediately highlighted the difference in approach the two products were taking and allowed me to adjust my expectations and how I navigated going forward.

Tech Docs

One of the promised features of internal developer portals is all the technical documentation lives in one place. Every large organization I’ve worked in struggles with the problem of documentation. Whether there isn’t enough, there’s too much, it’s outdated, there are too many locations for it, or somehow all of the above. I’ve seen attempts to solve this many times with new tools or products, but it seems more of an organizational and cultural issue than one that can be solved by a technical solution. Here’s how each platform chose to tackle the problem.


Backstage takes a docs like code approach to its tech docs. They espouse that documentation should be kept as close to the code as possible and be under source control. Backstage accomplishes this by making the tech docs available inside the backstage portal. The docs are generated as a static site from markdown files located inside your repository. You can even create an ‘entity’ within your software catalog that only contains documentation in the event you need to document a larger system, or maybe onboarding.

This is a standard plugin so I didn’t have to do anything other than add some configuration to my config-info.yml file in my repo and create a docs folder with an file. I was also able to add it to my software template (which we’ll cover later), so that any new services I create have a basic doc structure built into the repository.


Port did not have quite the same commitment to technical documentation that backstage had. This did not seem to be one of their core features. Port allows for the creation of custom pages and dashboard, and even nested folders of custom pages that you can fill with markdown documents. So, I’m sure you could create whatever documentation you wanted within those pages. This is arguably a more flexible approach as you aren’t limited to markdown. I added a Test markdown file by clicking the + Add Visualization button. You’ll also note the README from the repository is available in its own tab within the service details.

Again, I think this highlighted the difference in approaches for these two products. Backstage opting to take more of a configuration and code approach, while Port created a more ‘user friendly’ approach allowing clicking and adding. As far as I could tell the Port approach did not allow for source control of the docs created on its dashboard.

Check Out Part 2

Thanks for reading part 1 of my internal developer portal: Backstage vs Port series. Stay tuned for the next installment where I’ll continue my proof of concept by exploring scorecards, software templates, CI/CD Integration, and give my overall opinion on this trend.

Part 2