Let’s be real—developer productivity is a mess in most organizations. Not because the engineers aren’t talented, but because they’re drowning in context switching. You know the drill: jumping between Jenkins, Grafana, PagerDuty, and a dozen wikis just to deploy a microservice. It’s exhausting. That’s where Backstage comes in. It’s not just another tool—it’s a unified frontend for your entire engineering ecosystem. Think of it as a concierge for your codebase. Let’s break down how to build an internal developer portal with Backstage, and why it might just save your team’s sanity.
What Exactly Is Backstage?
Backstage is an open-source platform originally built by Spotify. They open-sourced it in 2020, and it’s now a CNCF incubating project. In simple terms, it’s a developer portal that centralizes all your tools, services, documentation, and infrastructure into one place. No more bookmarking 50 different URLs. No more asking “Hey, where’s the API docs for the payment service?”
Honestly, the best analogy I’ve heard is this: Backstage is like the dashboard of a car. You don’t need to know how the engine works to see your speed or fuel level. Similarly, developers don’t need to memorize every CI/CD pipeline—they just click a button in Backstage.
Why Now? The Pain Point
Organizations with more than a handful of microservices face a real problem: discovery. New hires spend weeks just figuring out what services exist. Teams duplicate efforts because they didn’t know a library already existed. And let’s not even talk about the chaos of onboarding—it’s a nightmare. Backstage solves this by acting as a single source of truth. It’s like a library catalog, but for your code.
Core Components of a Backstage Portal
Before you dive into building, you need to understand the building blocks. Backstage is modular—thankfully. Here’s what you’ll typically set up:
- Software Catalog – The heart of Backstage. It registers all your services, libraries, websites, and pipelines. Each entity has metadata (owner, tech stack, links to docs).
- Software Templates – Scaffold new projects with a few clicks. No more copy-pasting boilerplate from a wiki.
- TechDocs – Documentation-as-code. Write Markdown, store it in your repo, and it renders beautifully in Backstage. No more stale Confluence pages.
- Plugins – Integrate with GitHub, GitLab, Jenkins, Datadog, PagerDuty, you name it. There’s a growing ecosystem.
- Search – Global search across all entities, docs, and plugins. It’s surprisingly fast.
Sure, you can customize almost everything. But these five components are the foundation. Start there.
Step-by-Step: Setting Up Backstage
Alright, let’s get our hands dirty. I’ll walk you through the high-level steps. Note: This isn’t a full tutorial—more of a roadmap. You’ll need basic knowledge of Node.js, Docker, and Kubernetes (if you’re deploying it).
1. Scaffold Your Backstage App
Backstage provides a CLI tool called @backstage/create-app. Run it, answer a few questions, and boom—you have a skeleton app. It includes a frontend (React) and backend (Node.js). The default setup is opinionated, but that’s a good thing. It gives you a working portal in minutes.
Pro tip: Use the --template flag if you want a specific starting point. But honestly, the default is fine for most teams.
2. Configure the Software Catalog
This is where the magic happens. You’ll define entities in YAML files (usually stored in your repos). Each entity has a kind (Component, API, Resource, etc.) and metadata. For example:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-service
description: Handles payment processing
annotations:
github.com/project-slug: myorg/payment-service
spec:
type: service
lifecycle: production
owner: team-paymentsYou can automate this with a script that scans your repos. Or use the built-in entity provider to sync from GitHub. The goal is to keep the catalog alive—no manual updates.
3. Add Plugins for Your Stack
Plugins extend Backstage’s functionality. Want to see CI/CD status? Add the Jenkins plugin. Need on-call schedules? Add PagerDuty. There’s even a plugin for Kubernetes. The install process is usually just yarn add and a bit of config. Some plugins are more complex, but the community docs are solid.
One thing I’d caution: Don’t go plugin-crazy on day one. Pick 3–5 that solve your biggest pain points. You can always add more later.
4. Set Up TechDocs
TechDocs is a game-changer. It reads Markdown files from your repos and renders them in Backstage. No more hunting for a README that’s buried in a subfolder. To enable it, you need to configure a techdocs-backend plugin and a storage provider (like AWS S3 or Google Cloud Storage). It’s a bit fiddly, but worth it.
Here’s a pro move: Use mkdocs or Docusaurus for your documentation site, then point TechDocs at it. That way, your docs are both in Backstage and standalone.
5. Deploy and Iterate
You can run Backstage locally for testing, but production deployment usually means Docker + Kubernetes. There’s a Helm chart available. Or use a PaaS like Fly.io. Once it’s live, gather feedback. Ask your developers: “What’s missing? What’s confusing?” Iterate fast. Remember, this is a living tool—not a one-and-done project.
Common Pitfalls (And How to Avoid Them)
I’ve seen teams stumble. Here’s what to watch out for:
- Over-engineering the catalog – You don’t need to register every single script. Start with services and APIs. Add more later.
- Ignoring permissions – Backstage has a role-based access control system (RBAC). Use it. Not everyone needs to see production secrets.
- Neglecting search – The default search is decent, but you can improve it with Elasticsearch integration. Do it early.
- Forgetting about onboarding – Build a “Getting Started” template that new hires can use to create their first service. It’s a huge win.
Also, don’t try to migrate everything at once. Pick a pilot team—maybe the platform team—and let them be the guinea pigs. Once they love it, word spreads.
Table: Key Backstage Plugins by Category
| Category | Plugin Name | What It Does |
|---|---|---|
| CI/CD | Jenkins | Shows build status and triggers |
| Monitoring | Datadog | Displays dashboards and alerts |
| Incident Mgmt | PagerDuty | On-call schedules and escalation |
| Source Control | GitHub/GitLab | Repo details, PRs, and issues |
| Kubernetes | Kubernetes | Pod status and logs |
| Documentation | TechDocs | Render Markdown docs |
This table isn’t exhaustive, but it covers the essentials. The community is active—new plugins pop up monthly.
Real-World Impact: A Quick Story
I worked with a mid-sized fintech company that had 40+ microservices. Onboarding took two weeks. After implementing Backstage, it dropped to three days. How? The catalog showed every service’s owner, docs, and dependencies. New hires could spin up a template service in minutes. The CTO said it was the “best investment in developer experience we’ve ever made.” That’s not hyperbole—it’s real.
But here’s the thing: Backstage isn’t a silver bullet. If your engineering culture is chaotic (no ownership, no documentation), a portal won’t fix that. It amplifies what’s already there. So before you build, clean house a little. Define ownership. Write some docs. Then let Backstage organize the chaos.
Is It Worth the Effort?
Honestly, yes—if you have more than 10 developers and a growing microservice landscape. The setup takes a few weeks, but the payoff is continuous. Less context switching. Faster onboarding. Fewer “where is the X?” Slack messages. It’s like cleaning your garage: painful at first, but you wonder why you didn’t do it sooner.
That said, Backstage has a learning curve. The documentation is decent, but sometimes you’ll hit a wall. The community Discord is your friend. And don’t be afraid to fork the code—it’s open source, after all.
Final Thoughts
Building an internal developer portal with Backstage isn’t just about technology—it’s about reducing friction. It’s about giving your team back hours of wasted time. The best portals feel invisible; they just work. And when they do, developers stop complaining about tooling and start building cool stuff.
So go ahead. Scaffold that app. Register a few services. Add a plugin or two. You might be surprised how quickly