How much time do your developers spend figuring out who owns which microservice? Where’s the documentation? How is it deployed? What are its dependencies? Backstage by Spotify — now a CNCF incubating project — solves exactly this. A single place for your organization’s entire software ecosystem.
What Is Backstage¶
Backstage is an open-source platform for building developer portals. Spotify developed it internally for their 2,000+ engineers and open-sourced it in 2020. By 2023, it’s a CNCF incubating project with a massive community — over 100 plugins, adopted by Spotify, Netflix, American Airlines, HP, IKEA, and dozens more.
The core rests on three pillars: Software Catalog (a registry of all services, libraries, pipelines, and infrastructure), Software Templates (golden paths for creating new projects), and TechDocs (documentation as code, right in the repository).
Software Catalog — No More “Who Owns This?”¶
Every service, library, API, database, pipeline — everything is an entity in the catalog. Defined by a YAML file directly in the repository:
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-service
description: Payment microservice
tags: [java, spring-boot, payments]
spec:
type: service
lifecycle: production
owner: team-payments
dependsOn: [component:user-service]
The result: open Backstage, find payment-service, see who owns it (team-payments), its status (production), dependencies, where it runs, its APIs, and how to deploy it. No more Slack messages asking “hey, who owns that payment service?”
Software Templates — Golden Paths¶
A new developer needs to create a microservice. Without Backstage: they clone an existing project, delete what they don’t need, forget about CI/CD, and misconfigure monitoring. With Backstage: they click “Create,” select the “Java Spring Boot Service” template, fill in the name and description — and get a complete repository with CI/CD pipeline, Dockerfile, Helm chart, monitoring dashboard, and catalog registration.
Templates are defined as code (Nunjucks + YAML). This allows the organization to codify best practices — every new project starts the right way. That’s the essence of platform engineering: golden paths, not mandates.
TechDocs — Documentation That Lives¶
Backstage integrates a docs-as-code approach. Markdown files in the repository are automatically built (MkDocs) and displayed directly in the portal alongside the service. Documentation is always up to date because it lives with the source code. A pull request on code = a pull request on documentation.
For teams accustomed to Confluence, this is a cultural shift — but a significantly more efficient one. Documentation that nobody updates is worse than no documentation at all.
Plugin Ecosystem¶
Backstage is extensible through plugins. The community and ecosystem in 2023 offer plugins for:
- Kubernetes: pod status directly in the portal
- CI/CD: GitHub Actions, Jenkins, ArgoCD — build status in one place
- Monitoring: Grafana dashboards, PagerDuty incidents
- Cloud cost: AWS/Azure cost per service
- API docs: OpenAPI/Swagger directly in the catalog
- Security: Snyk vulnerabilities, SonarQube quality gates
Custom plugins are written in TypeScript/React. Backstage is essentially a React application with a plugin architecture — frontend developers feel right at home.
Deployment in Czech Enterprise¶
We deployed Backstage at a mid-sized bank (15 dev teams, 200+ microservices). Key challenges:
Adoption: the biggest hurdle isn’t technical. It’s convincing teams to maintain catalog-info.yaml files in their repositories. Solution: automation — a CI check that blocks merges without a valid catalog file.
Authentication: integration with corporate Azure AD via OIDC. Backstage supports Microsoft, GitHub, Google, Okta — standard flows.
Hosting: Backstage runs as a Node.js application + PostgreSQL. We deployed on AKS (Azure Kubernetes Service). A Helm chart is available but requires customization.
Results after 6 months: 95% of services in the catalog. New developer onboarding went from 2 weeks to 3 days. The number of Slack messages asking “who owns X” dropped by 80%.
Alternatives¶
Port: a managed developer portal — less work but vendor lock-in. Cortex: a similar concept, SaaS. OpsLevel: service catalog + maturity scorecards. Backstage is the only fully open-source and CNCF-backed option — for enterprises with internal customization requirements, it’s typically the best choice.
Platform Engineering Starts with a Developer Portal¶
Backstage isn’t just a tool — it’s a culture shift. From “every team does things their own way” to “we have a shared platform with golden paths.” The investment in deployment pays off through faster onboarding, reduced cognitive load, and consistency across the organization.
Need help with implementation?
Our experts can help with design, implementation, and operations. From architecture to production.
Contact us