Stage 7 · Master
Developer Portal & Software Catalog
Why a Developer Portal?
Solve fragmentation: single pane of glass for services, ownership, docs, deployments, and incidents.
6 min readPlatform Engineering & Developer ExperienceMaster
The Fragmentation Problem
As organizations scale, developer tooling fragments: CI in GitHub Actions, CD in ArgoCD, logs in Loki, metrics in Prometheus, traces in Tempo, docs in Confluence, ownership in spreadsheets, incidents in PagerDuty. Developers context-switch across 10+ tools daily.
| Without Portal | With Portal |
|---|---|
| 'Where is the dashboard for service X?' | Search service → see all dashboards, logs, traces |
| 'Who owns this service?' | Catalog shows owner, on-call, Slack channel |
| 'How do I deploy?' | Golden path scaffold → deploy in minutes |
| 'Is there a Python template?' | Template library with search, ratings, docs |
| 'What changed in platform v2.3?' | Changelog in portal, in-app notifications |
| 'How do I request a database?' | Self-service: platform db create postgresql |
What a Portal Solves
- Discovery: Find services, APIs, templates, documentation in one place
- Ownership: Clear ownership, on-call, contact info for every component
- Self-Service: Scaffold, provision, deploy, debug without tickets
- Standards: Scorecards show compliance with golden path, security, reliability
- Documentation: TechDocs alongside code, versioned, searchable
- Feedback: In-app feedback, friction logs, DX surveys
Core Portal Capabilities
| Capability | Description | Example |
|---|---|---|
| Software Catalog | Graph of entities: services, APIs, resources, systems, teams | Service → owns → Team; Service → dependsOn → Database |
| Scaffolder | Parameterized templates that generate repos + CI/CD + docs | platform scaffold go-service --name payments |
| TechDocs | MkDocs-based docs from markdown/OpenAPI, versioned with code | API reference auto-generated from OpenAPI spec |
| Scorecards | Compliance checks: golden path, security, reliability, ops maturity | Bronze/Silver/Gold badges on service entity |
| Search | Unified search across catalog, docs, templates, changelog | Type 'payments' → service, template, docs, incidents |
| Plugins | Extensible: Kubernetes, ArgoCD, Grafana, PagerDuty, GitHub, Jira | ArgoCD plugin shows sync status on service page |
Build vs Buy
| Option | Pros | Cons | Best For |
|---|---|---|---|
| Backstage (Self-Hosted) | Full control, open source, huge plugin ecosystem, free | Operational burden, upgrade complexity, needs dedicated team | Orgs with platform team, custom needs |
| Backstage (Managed: Roadie, Spotify) | No ops burden, managed upgrades, support | Cost, less customization, vendor lock-in | Orgs without platform ops capacity |
| Port / Cortex / OpsLevel | SaaS, purpose-built, opinionated, fast setup | Less flexible, vendor lock-in, cost per developer | Orgs wanting quick time-to-value |
| Custom Portal | Tailored to exact needs, own the stack | High build cost, maintenance burden, reinventing wheels | Unique requirements, strong platform team |
Portal Is Not the Platform
The portal is the *interface* to the platform. You can have a platform without a portal (CLI/API only), but you can't have a useful portal without a platform backend. Build the platform APIs first, then the portal.
Driving Adoption
- Make it the default: New hires get portal link day 1; all docs in portal
- Integrate with workflow: GitHub PR checks link to portal service page
- Gamify: Scorecards with Bronze/Silver/Gold — teams compete
- Executive sponsorship: Leadership references portal in all-hands
- Feedback loop: 'Was this helpful?' on every page → PM reviews weekly
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.