Developer Portals: Backstage vs Port vs Cortex

Introduction

Internal developer platforms (IDPs) have become essential for scaling engineering organizations. Developer portals serve as the front door, providing a unified interface for service discovery, documentation, provisioning, and operational tasks.

Three platforms have emerged as leaders: Backstage (Spotify/Netflix), Port, and Cortex. Each offers distinct approaches to solving developer experience challenges.

This guide compares these platforms to help you choose the right foundation for your internal developer platform.

Understanding Developer Portals

Core Capabilities

• Service Catalog: Discover and track all services and APIs
• Documentation: Centralized technical documentation
• Provisioning: Self-service resource creation
• Templates: Standardized scaffolding for new projects
• Observability: Integration with monitoring and alerting

Backstage

Overview

Backstage is an open-source developer portal originally built at Spotify and now a CNCF sandbox project.

Architecture

┌─────────────────────────────────────────────────────────┐
│                      Backstage                           │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │                   Frontend                         │   │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐  │   │
│  │  │Catalog │ │Docs    │ │Plugins │ │Templates│  │   │
│  │  └────────┘ └────────┘ └────────┘ └──────────┘  │   │
│  └──────────────────────────────────────────────────┘   │
│                           │                             │
│  ┌──────────────────────────────────────────────────┐   │
│  │                  Backstage Core                   │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌───────────┐  │   │
│  │  │  Router    │  │   Auth     │  │  Config  │  │   │
│  │  └─────────────┘  └─────────────┘  └───────────┘  │   │
│  └──────────────────────────────────────────────────┘   │
│                           │                             │
│  ┌──────────────────────────────────────────────────┐   │
│  │                   Plugins                          │   │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐   │   │
│  │  │ Kubernetes│ │GitHub │ │PagerDuty│ │  Tech Docs │  │   │
│  │  └────────┘ └────────┘ └────────┘ └──────────┘   │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Installation

# Create Backstage app
npx @backstage/create-app@latest

# Start locally
cd my-backstage-app
yarn install
yarn start

# Deploy to Kubernetes
kubectl create namespace backstage
helm install backstage backstage/backstage

Configuration Example

# app-config.yaml
app:
  title: My Company Developer Portal
  baseUrl: https://backstage.example.com

catalog:
  locations:
    - type: url
      target: https://github.com/org/repo/catalog-info.yaml
      rules:
        - allow:
            - Component
            - API
            - Resource
            - User
            - Group

github:
  token: ${GITHUB_TOKEN}
  organization: my-org

proxy:
  '/pagerduty/api':
    target: https://api.pagerduty.com
    headers:
      Authorization: Token token=${PAGERDUTY_TOKEN}

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

permission:
  enabled: true

Entity Definition

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  description: My microservice
  tags:
    - nodejs
    - typescript
    - rest-api
  annotations:
    github.com/project-slug: my-org/my-service
    jira/project-key: MYPROJ
spec:
  type: service
  lifecycle: production
  owner: team-backend
  system: order-system
  providesApis:
    - order-api
  dependsOn:
    - resource:payment-api

---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api
  description: Order service API
spec:
  type: openapi
  lifecycle: production
  owner: team-backend
  definition:
    type: url
    url: https://github.com/my-org/my-service/blob/main/openapi.yaml

Plugins Ecosystem

# Install popular plugins
yarn add @backstage/plugin-kubernetes
yarn add @backstage/plugin-gitlab
yarn add @backstage/plugin-jira
yarn add @backstage/plugin-aws
yarn add @backstage/plugin-lighthouse

Port

Overview

Port is a developer platform that combines a service catalog with self-service capabilities and developer experience features.

Architecture

┌─────────────────────────────────────────────────────────┐
│                         Port                             │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │              Visual Builder                        │   │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐  │   │
│  │  │Self     │ │Service │ │ Software│ │  Cost    │  │   │
│  │  │Service  │ │Catalog │ │ Catalog │ │  Center  │  │   │
│  │  └────────┘ └────────┘ └────────┘ └──────────┘  │   │
│  └──────────────────────────────────────────────────┘   │
│                           │                             │
│  ┌──────────────────────────────────────────────────┐   │
│  │              Port Agent                           │   │
│  │  ┌────────┐ ┌────────┐ ┌────────┐              │   │
│  │  │GitHub   │ │ Jira   │ │  K8s   │              │   │
│  │  │Exporter │ │Exporter│ │ Exporter│              │   │
│  │  └────────┘ └────────┘ └────────┘              │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Setup

# Install Port agent
helm repo add port-labs https://port-labs.github.io/port-helm-charts
helm install port-agent port-labs/port-agent \
  --set port.clientId=${PORT_CLIENT_ID} \
  --set port.clientSecret=${PORT_CLIENT_SECRET} \
  --set port.baseUrl=https://api.getport.io

Configuration

# port-config.yaml
resources:
  - kind: service
    selector:
      query: .metadata.annotations."port.io/derive" == "true"
    port:
      entity:
        apiVersion: port.io/v1alpha
        kind: Service
        metadata:
          title: .metadata.name
        spec:
          owner: .spec.owner
          tier: .metadata.labels.tier
          type: .spec.type
  - kind: github-workflow
    selector:
      query: .type == "workflow"
    port:
      entity:
        apiVersion: port.io/v1alpha
        kind: GithubWorkflow
        metadata:
          title: .name
        spec:
          repository: .repo.name
          path: .path

Self-Service Actions

# Port action definition
name: Create New Service
identifier: create-service
icon: GithubActions
description: Creates a new service from template

trigger:
  type: webhook
  webhook:
    url: https://api.getport.io/v1/webhooks/service-create
    method: POST

userInputs:
  properties:
    serviceName:
      type: string
      title: Service Name
    team:
      type: string
      title: Team
      enum:
        - team-backend
        - team-frontend
        - team-platform
    repositoryUrl:
      type: string
      title: Repository URL

 blueprint: service

Cortex

Overview

Cortex focuses on serviceCatalog, scorecards, and developer experience with a cloud-first approach.

Features

• Service Catalog: Track all services with metadata
• Scorecards: Define and track reliability standards
• Documentation: Centralized docs with templates
• Resources: Track cloud resources per service

Setup

# Deploy via Helm
helm repo add cortex https://cortexlabs.github.io/cortex-helm-charts
helm install cortex cortex/cortex \
  --set provider.aws.enabled=true \
  --set config.storage=dynamodb

Configuration

# cortex-config.yaml
provider: aws
cluster_name: production

storage:
  type: dynamodb
  tableName: cortex

providers:
  github:
    enabled: true
    token: ${GITHUB_TOKEN}
    webhookSecret: ${WEBHOOK_SECRET}

  kubernetes:
    enabled: true
    clusterName: production

  prometheus:
    enabled: true
    address: http://prometheus:9090

Comparison Matrix

Decision Framework

Choose Backstage If:

• You want full control and customization
• Strong engineering team for maintenance
• Need extensive plugin ecosystem
• Prefer open-source

Choose Port If:

• Quick time-to-value is critical
• Want managed solution
• Need strong self-service
• Prefer visual configuration

Choose Cortex If:

• Simplicity is paramount
• Scorecards are important
• AWS-native workloads
• Team is smaller

Implementation Patterns

Backstage + Kubernetes

# Backstage plugin for K8s
# Install plugin
yarn add @backstage/plugin-kubernetes

# Configure in app-config.yaml
kubernetes:
  serviceLocatorMethod:
    type: 'multiTenant'
  clusterLocatorMethods:
    - configMap:
        name: kubernetes-cluster

Port + GitHub Actions

# .github/workflows/port.yml
name: Sync to Port
on:
  push:
    branches:
      - main
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: port-labs/port-action@v1
        with:
          identifier: ${{ github.repository }}
          title: ${{ github.repository }}
          blueprintId: service
          properties: |
            {
              "description": "${{ github.repository_description }}",
              "repository": "${{ github.repository }}",
              "team": "${{ github.repository_owner }}"
            }

Implementation Checklist

Planning

• Define scope and goals
• Identify key stakeholders
• Plan integration points

Implementation

• Install platform
• Configure integrations
• Set up service catalog
• Create templates

Adoption

• Onboard teams
• Train users
• Gather feedback
• Iterate

Summary

All three platforms serve the internal developer platform need:

1. Backstage offers maximum customization through plugins but requires more maintenance.

2. Port provides the fastest path with managed solution and strong self-service.

3. Cortex delivers simplicity with native scorecards and AWS focus.

Choose based on your team’s capabilities, timeline, and specific requirements.

External Resources

• Backstage Documentation
• Backstage GitHub
• Port Documentation
• Cortex Documentation
• CNCF Backstage