An Internal Developer Portal (IDP) reduces the time developers spend searching for services, spinning up new projects, and finding documentation, from hours to minutes. This guide covers the three pillars of IDP design: a well-modeled software catalog, scaffolding templates, and an automated TechDocs pipeline, built on Backstage.
Why Most Backstage Setups Fail After the Tutorial
The “hello world” Backstage tutorial gets you a running portal in an afternoon. What it doesn’t tell you:
- A catalog with poor entity modeling becomes a dumping ground nobody trusts
- Scaffolding templates without enforcement create more inconsistency, not less
- TechDocs that live outside the portal are docs that don’t get read
Getting an IDP right is an architectural decision, not a configuration task. That distinction matters most for CTOs and engineering leaders deciding whether to build, buy, or integrate.
Pillar 1: Catalog Entity Modeling, Get This Wrong and Nothing Else Matters
The software catalog is the foundation. Every other feature depends on it being accurate.
What to model
Backstage uses YAML-defined entities. The four you’ll use most:
- Component : a service, website, library, or pipeline
- System : a group of components that deliver a business capability
- Domain : a high-level business area owning multiple systems
- API : a contract between components (OpenAPI, gRPC, AsyncAPI)
Common mistakes in catalog design
- Flat structure : registering every microservice as a standalone Component with no System or Domain parent. Three months in, you have 200 components with no grouping logic
- Missing ownership : skipping the spec.owner field. Without ownership, the catalog can’t answer “who do I call when this breaks?”
- Manual registration only : relying on developers to add catalog-info.yaml by hand. Adoption dies within weeks
What works instead
# catalog-info.yaml — well-modeled Component
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payments-service
annotations:
github.com/project-slug: org/payments-service
backstage.io/techdocs-ref: dir:.
spec:
type: service
lifecycle: production
owner: group:payments-team
system: checkout-system
dependsOn:
- component:fraud-detection-service
providesApis:
- payments-api - Use automated discovery via GitHub org integrations, Backstage scans repos for catalog-info.yaml automatically
- Enforce the schema in CI with backstage-cli validation
- Assign Domain ownership to a business unit, not just an engineering team
Pillar 2: Software Templates for Scaffolding, Standardize Without Slowing Down
Scaffolding templates answer: “How do we start a new service the right way, every time?”
What scaffolding templates solve
Without templates:
- New services miss security baselines
- CI/CD pipelines are copy-pasted from old repos with outdated configs
- README files are either blank or copy-pasted from somewhere irrelevant
How Backstage Software Templates work
Templates are YAML-defined wizards. A developer fills a form in the portal. Backstage:
- Clones a skeleton repo
- Substitutes variables (service name, owner, region)
- Creates a GitHub repo with branch protection pre-configured
- Registers the new Component in the catalog automatically
- Triggers the first CI pipeline
What to include in every template
- Language/runtime baseline : Node.js, Python, Java starters with linting, formatting, and dependency scanning configured
- CI/CD pipeline : GitHub Actions or your pipeline of choice, wired and ready
- Observability hooks : structured logging, metrics endpoint, health check route
- catalog-info.yaml pre-filled : the new service appears in the catalog the moment it’s created
- Security defaults : secrets scanning, SAST tool, dependency audit
The critical governance step most teams skip
Templates without version control become stale. Treat them like production code:
- Store in a dedicated backstage-templates repo
- Review and update quarterly
- Deprecate old templates explicitly rather than letting them rot
Pillar 3: TechDocs Pipeline, Documentation That Stays Alive
TechDocs is Backstage’s built-in docs-as-code system. It renders Markdown files stored alongside your code directly inside the portal.
Why this matters
Documentation that lives outside the codebase gets outdated. Documentation that lives inside the repo but requires a separate tool to read doesn’t get read. TechDocs closes both gaps.
How to set up the pipeline
- Store docs/ folder in the same repo as the service
- Add mkdocs.yml at the root
- Configure the TechDocs builder in your CI pipeline, it compiles Markdown into a static site on every merge
- Backstage serves it directly from the component page
What good TechDocs architecture looks like
- Architecture Decision Records (ADRs) : stored in docs/adr/, linked from the component catalog page
- Runbooks : operational guides co-located with the service, not in a separate Confluence space
- API reference : auto-generated from OpenAPI specs, not hand-written
The Business Case for Decision Makers
An IDP done right reduces:
- Onboarding time : new engineers find services, owners, and docs without asking on Slack
- Incident resolution time : runbooks and dependency maps are in one place
- Compliance overhead : ownership, lifecycle, and API contracts are auditable from the catalog
This is not a developer convenience project. It is an intelligent business transformation initiative, standardizing how your engineering organization scales, ships, and operates software.
At 200OK Solutions, we design and implement IDPs as part of broader intelligent business transformation engagements, from catalog modeling through full developer platform rollout.
FAQs
Q. How long does it take to design an internal developer portal on Backstage?
A working catalog with 2–3 templates and TechDocs can be production-ready in 6–8 weeks. Full org-wide adoption takes 3–6 months depending on engineering team size.
Q. Do we need to self-host Backstage?
Backstage is open-source and typically self-hosted. Managed options (Roadie, Spotify-internal) exist but limit customization. For most mid-to-large engineering teams, self-hosting gives more control.
Q. What’s the difference between a software catalog and a service registry?
A service registry tracks runtime instances. A software catalog tracks ownership, dependencies, APIs, and documentation at the architectural level. Both are useful; they solve different problems.
Q. How does an IDP support intelligent business transformation?
An IDP makes your engineering capabilities visible, governable, and scalable, the technical foundation for any serious transformation initiative.
You may also like : Deployment Platform Showdown: Harness, ArgoCD, Spinnaker
