Backstage
Backstage is an open framework for building developer portals
Conteúdo
Links
🎯 O que é o Backstage
Backstage é uma plataforma open-source criada pela Spotify para gerenciar ferramentas, serviços e documentação de desenvolvimento em um só lugar. 👉 É como um “portal interno de desenvolvedores” — um painel central para todo o ecossistema técnico da empresa.
🧱 Conceito principal
A ideia é ter um único ponto de acesso para:
- serviços (APIs, apps, libs internas),
- documentação técnica,
- pipelines CI/CD,
- monitoramento, métricas,
- e ferramentas de dev (Kubernetes, GitHub, etc).
Tudo configurado de forma modular e extensível.
⚙️ Principais recursos
| Categoria | Descrição |
|---|---|
| 🧩 Software Catalog | Registra e lista todos os serviços da empresa (apps, APIs, libs). |
| 📚 TechDocs | Gera documentação técnica automática a partir de arquivos Markdown no repositório. |
| 🧰 Plugins | Sistema de plugins (oficiais e customizados) para integrar ferramentas como GitHub, Jenkins, Kubernetes, Grafana, etc. |
| 🚀 Software Templates | Automatiza criação de novos serviços/projetos (boilerplates, scaffolding). |
| 🔐 Auth & RBAC | Controle de acesso e autenticação (GitHub, Google, LDAP etc). |
| 🎛️ App extensível | Interface web React + backend Node.js — totalmente personalizável. |
🧠 Como ele é usado
- Grandes empresas usam como Developer Portal interno (IDP).
- Cada time registra seus serviços e docs.
- Ferramentas e pipelines ficam acessíveis em um só dashboard.
💻 Stack técnica
- Frontend: React
- Backend: Node.js / Express
- Infraestrutura: Plugins conectam-se a GitHub, Jenkins, Kubernetes, etc.
- Deploy: Pode rodar em Docker, Kubernetes ou localmente.
🌍 Site e recursos
- Site oficial: https://backstage.spotify.com
- Código-fonte: https://github.com/backstage/backstage
🔧 Resumo prático
“Backstage é o hub central para times de engenharia — um portal unificado que integra código, documentação, pipelines e métricas em um único lugar.”
Perfeito 👌 — aqui vai um diagrama simples e didático mostrando como o Backstage se encaixa no ecossistema de desenvolvimento.
🧭 Visão Geral do Backstage (conceito simplificado)
┌──────────────────────────────────────────┐
│ 🌐 Backstage Portal │
│------------------------------------------│
│ 🧩 Software Catalog │
│ 📚 TechDocs (docs.md → site) │
│ 🚀 Templates (scaffolding de projetos) │
│ 📊 Plugins (Grafana, Jenkins, etc.) │
└──────────────────────────────────────────┘
▲
│
│ APIs / Plugins
│
┌───────────────────────────┼───────────────────────────┐
│ │ │
┌───────────────┐ ┌──────────────┐ ┌─────────────────┐
│ GitHub / │ │ CI/CD │ │ Observabilidade │
│ GitLab │◄───────►│ (Jenkins, │◄───────►│ (Grafana, Prom.)│
│ (código, docs)│ │ GitHub Act.)│ │ (logs, métricas)│
└───────────────┘ └──────────────┘ └─────────────────┘
▲
│
│ TechDocs Plugin lê markdown dos repositórios
│
┌────────────────────────────────┐
│ Repositórios de │
│ serviços, libs e docs │
│ (README.md, catalog-info.yaml) │
└────────────────────────────────┘
🧩 Resumo visual
- Repositórios (GitHub/GitLab) → guardam código e docs (
.mdecatalog-info.yaml) - Backstage Backend (Node.js) → lê essas infos e indexa no Software Catalog
- Frontend React → mostra tudo num painel web interno
- Plugins → conectam o portal a Jenkins, Grafana, Kubernetes, etc.
- Dev Portal Unificado → o time acessa tudo num só lugar
🗂️ Software Catalog
The fundamental unit within the catalog is an entity which represents some piece of your organization’s software ecosystem.
Software in the Backstage Software Catalog is often modeled in three different entities:
- Components are individual pieces of software
- APIs are the boundaries between different components
- Resources are physical or virtual infrastructure needed to operate a component
┌──────────┐ providesAPI ┌────────────┐ ┌───────────┐
│ │◄─────────────│ │ dependsOn │ │
│ API… │ consumesAPI │ Component… │──────────►│ Resource… │
│ │◄─────────────│ │ │ │
└──────────┘ └────────────┘ └───────────┘
It could become difficult to keep track of the relationships between various entities as a software catalog scales. Ecosystem modeling goes a step further by grouping these entities according to the following concepts:
- Systems are a collection of entities that cooperate to perform some function
- Domains relate entities and systems to part of the business This modeling concept forms an abstraction level (systems) that allows a consumer to better grasp how a software ecosystem works without having to know all the implementation details. When presented with a group of systems that share certain characteristics (eg: business purpose), these can be grouped together into Domains.
┌──────────┐ partOf ┌───────────┐ partOf ┌────────────┐
│ │◄─────────│ │◄────────────│ Resource… │
│ Domain │ │ │ └────────────┘
│ │ │ │ ▲
└──────────┘ │ System │ dependsOn │
│ │ │
│ │ partOf ┌────────────┐
│ │◄─────────────│ │
└───────────┘ │ │
▲ │ │
partOf │ │ │
│ │ Component… │
┌───────────┐ providesAPI │ │
│ │◄─────────────│ │
│ API… │ consumesAPI │ │
│ │◄─────────────│ │
└───────────┘ └────────────┘
To summarize, there are:
- Kinds of entities: Domain, System, Component, API, Resources, User, Group
- Types of entities: Service, Website, Library, OpenAPI, GraphQL, etc.
- Relationships of entities: ownedBy, providesApi, memberOf, dependencyOf
This model is not set in stone. It can be reworked and extended to fit your organization, just like custom resource definitions in Kubernetes. For example, in Spotify’s own installation we also model native applications and machine learning models.
Container diagram for Backstage System
https://backstage.spotify.com/learn/backstage-for-all/architecture-and-technology/7-container/
Components
https://backstage.spotify.com/learn/backstage-for-all/architecture-and-technology/8-component/
