Backstage, Port, and Developer Portals

A developer portal is not the platform — it is the front door to it. Done well, it gives every engineer a single place to discover services, understand ownership, scaffold new components, run common tasks, and see how their software measures against standards. Done badly, it is yet another internal tool nobody updates.

The Big Four

Smaller fish — Compass (Atlassian), OpsLevel, AWS Proton, GitHub Enterprise + Copilot for portals — also exist. Backstage and Port are the names you will hear most.

Backstage in One Page

Backstage is a React frontend, a Node.js backend, and a Postgres database. You install it, write some YAML, and write code to add functionality. It is genuinely flexible — and genuinely a real application your platform team must operate.

Core concepts

• Catalog — the inventory of everything. Defined by catalog-info.yaml files in each repo, ingested by Backstage. Entities: Component, API, System, Resource, Group, User, Domain.
• Scaffolder — software templates that create new repos, register them in the catalogue, configure CI/CD, etc. Driven by template YAML and a parameter form.
• TechDocs — Markdown-as-code documentation rendered from each component's repo. Static-site-style, searchable, owned by the team that owns the code.
• Plugins — everything else. CI status, deployment widget, cost dashboard, Kubernetes view, PagerDuty incidents. Hundreds in the community plugin marketplace.

A minimal catalog-info.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: checkout-service
  description: The checkout web service
  annotations:
    github.com/project-slug: acme/checkout-service
    backstage.io/techdocs-ref: dir:.
    pagerduty.com/integration-key: PXXXX
    grafana/dashboard-selector: "tags @> ['checkout']"
spec:
  type: service
  lifecycle: production
  owner: team-checkout
  system: payments
  providesApis:
    - checkout-api

That single file populates the service entry, its ownership, its docs, its on-call rotation, and its dashboards.

What it costs to run

• Hosting: a small Kubernetes deployment + Postgres + object storage for TechDocs
• Engineering: 1-3 platform engineers, ongoing — to maintain custom plugins and keep up with monthly Backstage releases (which break things)
• Onboarding: every team writes and maintains their own catalog-info.yaml

Port: The SaaS Alternative

Port takes a different stance: define your data model in their UI, push data via integrations or APIs, and use their action engine to wire self-service. No code to deploy. You trade the unlimited flexibility of Backstage for speed and operational simplicity.

Strengths: catalogue and scorecards are configured via the UI in hours; integrations with GitHub, Jenkins, ArgoCD, AWS, Datadog, PagerDuty are pre-built; pricing scales with users.

Weaknesses: customisation beyond what Port models is harder; your data lives in a vendor; cost can be material for larger orgs.

What a Portal Needs to Be Useful

1. Authoritative ownership data. Who owns this service? If the portal can't answer that, nothing else matters.
2. Real-time status. Build status, deploy status, on-call status — fresh enough to act on.
3. Self-service actions. Scaffold a new service, request a new database, rotate a secret. Without this, the portal is read-only and adoption stalls.
4. Search that works. Half the time someone visits the portal, they want to find one thing.
5. An obvious next click. The deploy widget points to the deploy; the on-call widget points to PagerDuty.

Software Templates: The Scaffolder Pattern

The scaffolder lets a developer fill in a form and get a fully wired service. Behind the scenes:

1. Render a template repo with their inputs
2. Create a new Git repo from it
3. Open a PR registering the component in the catalogue
4. Open a PR configuring deploy pipelines / namespaces / IAM
5. Send Slack confirmation with links

In Backstage this is YAML + the scaffolder backend. In Port it is the action engine with pre-built steps. Either way, the template encapsulates the company's standards — a kind of "policy as a wizard."

Scorecards (Maturity Models)

Almost every portal supports scorecards. Define standards as data — has README, has CODEOWNERS, has on-call, has SLO, log retention configured, etc. — and grade each service. We will go deeper in lesson 7.

Choosing

Anti-Patterns

• Setting up the tool before designing the data model. The catalogue is only as useful as the entities and ownership it represents. Spend the design time first.
• Generating the catalogue automatically from clouds, then leaving it. Stale ownership is worse than no ownership.
• Plugin overload. Twenty plugins, none of which the user looks at. Prefer five that drive a daily workflow.
• Operating Backstage as a side project. It is a real application; treat it like one.

The portal is a tool. The underlying capabilities — Kubernetes, CI, infra, observability — are the platform. Get those right first; the portal will follow.