---
title: "How to Build an Internal Developer Platform From Scratch 2026"
author: "Nate Laquis"
author_role: "Founder & CEO"
date: "2026-06-07"
category: "How to Build"
tags:
  - internal developer platform
  - platform engineering
  - Backstage IDP
  - developer experience
  - self-service infrastructure
excerpt: "Most platform engineering teams fail not because of bad tooling, but because they build a platform nobody asked for. Here is how to build an IDP that developers actually use."
reading_time: "15 min read"
canonical_url: "https://kanopylabs.com/blog/how-to-build-an-internal-developer-platform"
---

# How to Build an Internal Developer Platform From Scratch 2026

## Why Internal Developer Platforms Are No Longer Optional

Every growing engineering organization hits the same wall. At ten developers, someone asks where the staging environment config lives. At thirty developers, three teams are independently building their own deployment scripts. At fifty developers, onboarding a new hire takes two weeks because nobody can explain how to get a service running locally. This is the problem an internal developer platform solves, and in 2026, it is the single highest-leverage investment a scaling engineering team can make.

An internal developer platform (IDP) is a self-service layer that sits on top of your existing infrastructure and tooling. It gives developers a single interface to provision environments, deploy services, manage secrets, discover APIs, and follow standardized workflows. Instead of filing a Jira ticket and waiting three days for a DevOps engineer to create a database, a developer clicks a button and gets one in four minutes. Instead of copy-pasting Terraform modules from a wiki page that was last updated eight months ago, a developer selects a "golden path" template and gets a production-ready service scaffold with CI/CD, monitoring, and logging already wired up.

The business case is concrete. Puppet's 2025 State of Platform Engineering report found that organizations with mature IDPs saw a 30% reduction in time-to-production for new services and a 40% reduction in developer onboarding time. Humanitec's benchmarking data shows that teams with self-service infrastructure provisioning resolve environment-related blockers 5x faster than teams relying on ticket-based workflows. These numbers compound. A team of 40 developers saving 3 hours per week each on infrastructure friction reclaims 6,240 engineering hours per year. At a blended cost of $90/hour, that is $561,600 in recovered productivity annually.

![Developer workstation with code editor open showing platform engineering configuration files](https://images.unsplash.com/photo-1555949963-ff9fe0c870eb?w=800&q=80)

But here is the uncomfortable truth: most IDP initiatives fail. They fail because a platform team disappears into a room for six months, builds an elaborate portal, and emerges to discover that developers do not want it, do not trust it, and will not use it. Building an IDP is not a technology problem. It is a product problem. You need to treat your developers as customers, understand their actual pain points, and ship iteratively. This guide walks through every step of that process, from initial research through production rollout and long-term adoption.

## Step 1: Map Your Developer Experience Gaps Before Writing Any Code

The first mistake platform teams make is starting with a tool. They hear about Backstage at a KubeCon talk, get excited, and start building a service catalog before they have asked a single developer what their biggest frustration is. This is building a solution in search of a problem, and it almost always produces a platform that collects dust.

Start with research. Interview 8 to 12 developers across different teams, seniority levels, and tenure at the company. Ask specific questions: What took the longest when you last set up a new service? Where do you go to find out who owns a particular API? How do you request a new cloud resource? What is the most annoying part of your deployment process? How long did it take you to ship your first pull request after joining the company?

Track the answers and look for patterns. In our experience working with engineering teams at Kanopy, the top pain points almost always cluster around five areas:

- **Environment provisioning:** developers waiting days for staging environments, databases, or cloud resources because provisioning requires a DevOps engineer or a ticket in a queue.

- **Service discovery:** nobody knows what services exist, who owns them, what APIs they expose, or where their documentation lives.

- **Onboarding friction:** new developers spend their first week fighting local setup issues instead of shipping code.

- **Inconsistent tooling:** every team uses a slightly different CI/CD setup, a different logging approach, a different deployment process. Knowledge does not transfer between teams.

- **Configuration sprawl:** secrets, environment variables, feature flags, and infrastructure config are scattered across GitHub repos, AWS Parameter Store, Notion pages, and Slack messages.

Once you have identified your top three pain points, stack-rank them by two criteria: frequency (how often do developers hit this problem?) and severity (how much time or frustration does it cost each time?). The intersection of high frequency and high severity is where your IDP should start. Do not try to solve all five areas at once. Pick the one or two that will deliver the most relief and build those first. You can expand scope later once you have earned developer trust.

Document your findings in a one-page brief: the problem, who it affects, how often it occurs, and the measurable outcome you expect the platform to deliver. This brief becomes your North Star for the first iteration and prevents scope creep. It also gives you a clear metric to evaluate whether the IDP is actually working after launch.

## Choosing Your Foundation: Backstage vs Port vs Kratix vs Custom

Once you know what you are building, you need to decide how to build it. The IDP tooling landscape in 2026 has matured significantly, but the choices still carry meaningful tradeoffs. Here are the four approaches worth considering.

### Backstage (Spotify)

Backstage is the open-source developer portal originally built by Spotify and donated to the CNCF, where it graduated as an incubating project. It provides a service catalog, software templates, TechDocs (documentation-as-code), and a plugin architecture with over 200 community plugins covering everything from Kubernetes dashboards to PagerDuty integration. Backstage is written in TypeScript (React frontend, Node.js backend) and runs as a standalone application that your platform team deploys and manages.

The strengths are real: massive community, extensive plugin ecosystem, deep GitHub and Kubernetes integrations, and the credibility of being battle-tested at Spotify's scale. The weaknesses are also real. Backstage has a steep initial setup curve. Expect two to four weeks of dedicated engineering time to get a production-ready deployment with SSO, a populated service catalog, and three to five useful plugins configured. The plugin quality varies wildly. Some are polished and maintained. Others are abandoned proofs of concept. You will spend time evaluating, forking, and fixing plugins. Backstage also requires ongoing maintenance: dependency updates, security patches, and plugin compatibility management.

Backstage is the right choice if you have at least one dedicated platform engineer, you want maximum flexibility and customization, your team is comfortable with TypeScript, and you plan to invest in the platform long-term.

### Port

Port is a commercial IDP that takes a fundamentally different approach. Instead of building a portal from code, you define your internal developer portal through a visual builder and a data model. Port provides a service catalog, self-service actions (triggered via webhooks to your CI/CD pipelines or cloud APIs), scorecards for tracking engineering standards compliance, and a portal that requires zero frontend code to customize. It integrates with GitHub, GitLab, Kubernetes, AWS, GCP, Azure, PagerDuty, Datadog, and dozens more through pre-built connectors.

The strengths: dramatically faster time-to-value. A team can have a functional portal with a populated service catalog and two to three self-service actions running in three to five days, not weeks. The commercial support means you are not debugging plugin compatibility issues. The weakness is cost. Port's pricing starts at roughly $25 per developer per month for the growth tier, which adds up quickly at scale. You also trade customization depth for speed. If your requirements are unusual, you may hit the limits of what Port's visual builder can express.

Port is the right choice if you want fast time-to-value, do not have a dedicated platform engineer, and your budget can absorb the per-developer cost.

### Kratix and Crossplane

Kratix and Crossplane are not developer portals. They are infrastructure-layer tools that power the self-service provisioning engine behind a portal. Crossplane extends Kubernetes with custom resource definitions (CRDs) that let you provision cloud resources (RDS databases, S3 buckets, GCP Cloud SQL instances) by applying Kubernetes manifests. Kratix, built by Syntasso, sits a layer above Crossplane and provides a "platform-as-a-product" framework: you define "Promises" that describe what a team can request (e.g., "I need a PostgreSQL database with 100GB storage in us-east-1") and Kratix handles the orchestration, including any approval workflows, compliance checks, or dependency provisioning.

These tools are the right choice when self-service infrastructure provisioning is your primary pain point. They pair well with either Backstage or Port as the frontend layer. Most mature IDP architectures use a portal (Backstage or Port) for the developer-facing UI and Crossplane or Kratix for the infrastructure automation backend.

### Building Custom

Some teams decide to build their IDP from scratch: a custom React frontend, a custom API layer, custom integrations with every tool in their stack. This is almost never the right call. Custom builds take 6 to 12 months to reach feature parity with what Backstage gives you out of the box, and they accumulate maintenance burden rapidly. The only scenario where custom makes sense is if your requirements are so unique that no existing tool can accommodate them, which is rare. Start with an existing foundation and customize from there. Your platform engineers should spend their time on workflows and integrations that are specific to your organization, not rebuilding a service catalog for the hundredth time.

## Building Your Service Catalog: The Foundation Everything Else Depends On

A service catalog is the most important component of any IDP. It answers the question every developer asks constantly: what services exist, who owns them, and how do I interact with them? Without a catalog, developers rely on tribal knowledge, outdated wiki pages, and Slack searches. With a catalog, they open one page and get the full picture.

A good service catalog tracks every software component in your organization: backend services, frontend applications, libraries, data pipelines, infrastructure resources, and APIs. For each component, it stores metadata: the owning team, the repository URL, the deployment environment, the on-call rotation, the API documentation link, the tech stack, the last deployment timestamp, and the current health status. This metadata is what transforms a static list of services into a living, searchable knowledge base.

![Server room with rows of racks representing cloud infrastructure powering developer platforms](https://images.unsplash.com/photo-1504868584819-f8e8b4b6d7e3?w=800&q=80)

The critical design decision is where the catalog data lives. There are two schools of thought. The first approach stores catalog metadata in a central database managed by the platform team. This gives you strong consistency and easy querying, but it creates a maintenance burden: someone has to keep the catalog data in sync with reality, and it will drift. The second approach, which Backstage popularized, stores catalog metadata in YAML files (**catalog-info.yaml**) that live in each service's repository. The catalog ingests these files automatically and stays in sync because the data lives alongside the code. This "catalog-as-code" approach is better for most teams because it distributes the maintenance burden to the teams that own each service.

Here is what a minimal Backstage catalog descriptor looks like for a backend service:

**apiVersion:** backstage.io/v1alpha1**kind:** Component**metadata:** name: payments-service, description: Handles payment processing and subscription billing**spec:** type: service, owner: team-payments, lifecycle: production, system: billing

Start simple. Require every team to add a catalog descriptor with five fields: name, description, owner, type, and lifecycle stage. Do not mandate 30 metadata fields on day one. That creates friction and resistance. You can expand the schema incrementally as the catalog proves its value. The goal of the first version is adoption, not completeness.

Automate catalog population wherever possible. Write a script that scans your GitHub organization, identifies repositories that look like services (they have a Dockerfile, a deployment manifest, or a CI/CD workflow), and generates a pull request adding a **catalog-info.yaml** file to each one. This gets you to 80% coverage in a single afternoon. The remaining 20% requires manual outreach to teams, but the momentum of a nearly-complete catalog makes those conversations much easier.

Once the catalog is populated, connect it to your operational tools. Integrate with PagerDuty or OpsGenie to show on-call information per service. Integrate with your [CI/CD pipeline](/blog/how-to-set-up-cicd) to show the last deployment status. Integrate with Datadog or Grafana to show real-time health metrics. Each integration makes the catalog more useful and increases the chances that developers will actually open it instead of searching Slack.

## Golden Paths and Self-Service Infrastructure: Where the Real Value Lives

A service catalog tells developers what exists. Golden paths tell developers how to build new things the right way. Self-service infrastructure lets them provision what they need without waiting. Together, these two capabilities deliver the majority of an IDP's practical value.

### Golden Paths

A golden path is a pre-built, opinionated template for creating a new software component. When a developer needs to create a new backend service, they do not start from scratch. They select the "Node.js Backend Service" golden path from the platform, fill in a few parameters (service name, owning team, target cloud region), and the platform scaffolds a complete repository with a production-ready structure: source code skeleton, Dockerfile, CI/CD pipeline configuration, Terraform modules for the required infrastructure, monitoring dashboards, alerting rules, and a populated catalog descriptor.

The key word is "opinionated." A golden path encodes your organization's best practices. It decides which Node.js framework to use (Fastify, not Express, because your team standardized on Fastify for performance reasons). It decides how logging is configured (structured JSON logs sent to your central logging platform). It decides how health checks work (a **/healthz** endpoint that checks database connectivity). These decisions are not optional customizations. They are the standards your organization has agreed on, baked into a template so that every new service starts compliant instead of drifting toward compliance over months of review feedback.

In Backstage, golden paths are implemented through Software Templates, which are YAML-based workflow definitions that use scaffolding actions (create a GitHub repo, generate files from a Cookiecutter or Nunjucks template, register the new component in the catalog, trigger a CI/CD pipeline). In Port, they are implemented through Self-Service Actions with blueprints. Both approaches achieve the same result: a developer fills out a form and gets a fully configured service in minutes.

Start with two to three golden paths that cover your most common creation patterns. For most teams, that means: (1) a backend API service, (2) a frontend web application, and (3) a background worker or data pipeline. Do not try to template every possible service type. The long tail of unusual services can be created manually. The goal is to make the common case effortless.

### Self-Service Infrastructure

Self-service infrastructure provisioning eliminates the ticket queue between developers and cloud resources. Instead of requesting a PostgreSQL database through Jira and waiting for a DevOps engineer to provision it, a developer selects "PostgreSQL Database" from the platform, specifies the size and region, and gets a fully provisioned database with connection strings delivered to their service's environment variables in minutes.

The implementation pattern that has won in 2026 is Kubernetes-native provisioning with Crossplane. Here is how it works: Crossplane installs as a set of controllers in your Kubernetes cluster. You install provider packages for your cloud (AWS, GCP, Azure). You define Compositions that map a simple developer-facing API to the complex underlying cloud resources. A developer creates a Kubernetes custom resource that says "I want a PostgreSQL database, 50GB, in us-east-1" and Crossplane translates that into the necessary AWS API calls to create an RDS instance, configure security groups, set up automated backups, and store the connection string in a Kubernetes Secret.

Kratix adds a higher-level abstraction on top of this. With Kratix, you define "Promises" that bundle the Crossplane resource with additional business logic: approval workflows (databases over 500GB require manager approval), compliance checks (all databases must have encryption at rest enabled), and dependency provisioning (creating a database also creates a monitoring dashboard and an alerting rule). Promises turn raw infrastructure provisioning into a curated, guardrailed experience.

The combination of a portal frontend (Backstage or Port), golden path templates, and a Crossplane/Kratix backend gives you a complete self-service stack. Developers interact with a clean UI. Platform engineers define the abstractions. Cloud resources get provisioned with all your compliance and security requirements enforced automatically. This is the architecture pattern that Humanitec, the company behind the [platform engineering reference architecture](/blog/how-to-build-an-api-marketplace-developer-portal), recommends, and it has become the de facto standard for Kubernetes-native IDPs.

## CI/CD Integration, Kubernetes Abstractions, and Developer Experience Metrics

An IDP is only as useful as the workflows it connects. The three integration areas that matter most are CI/CD pipelines, Kubernetes deployment abstractions, and developer experience measurement.

### CI/CD Integration

Your IDP should not replace your CI/CD system. It should provide a unified view into it. Developers should be able to see the deployment status of every service, trigger deployments, roll back to previous versions, and view build logs without leaving the platform. In Backstage, the CI/CD plugin ecosystem covers GitHub Actions, GitLab CI, Jenkins, Argo CD, and Tekton. In Port, self-service actions can trigger GitHub Actions workflows or Argo CD syncs through webhook integrations.

The deeper integration opportunity is connecting your golden path templates to your [CI/CD pipeline](/blog/how-to-set-up-cicd). When a developer scaffolds a new service from a golden path, the template should include a complete, working CI/CD configuration. The developer should be able to push code and see it deployed to a preview environment within minutes of creating the service, with zero additional CI/CD setup required. This is the "it just works" experience that earns developer trust and drives adoption.

If you are running Argo CD for GitOps-based deployments, integrate your IDP's service catalog with Argo CD's application registry. When a developer creates a new service through a golden path, the template should also create the Argo CD Application manifest and commit it to your GitOps repository. This closes the loop: service creation, CI/CD configuration, and deployment orchestration are all handled in a single workflow.

### Kubernetes Abstractions

Raw Kubernetes manifests are not a developer interface. A deployment YAML file with 80 lines of configuration, most of which a developer should never need to think about, is a platform engineering failure. Your IDP should abstract Kubernetes complexity behind developer-friendly interfaces.

There are several approaches to this. Score (score.dev) provides a workload specification that lets developers describe what their service needs (container image, ports, environment variables, resource dependencies) without writing Kubernetes YAML. The platform translates the Score file into Kubernetes manifests, Helm charts, or Docker Compose files depending on the target environment. Humanitec's Platform Orchestrator takes a similar approach with its workload abstraction layer.

A simpler approach that works well for many teams is creating internal Helm charts or Kustomize overlays that expose only the parameters developers need to change. Instead of writing a full Deployment, Service, Ingress, HPA, and PDB manifest, a developer provides a values file with five fields: image tag, replica count, environment variables, resource requests, and health check path. The internal Helm chart handles everything else according to your organization's standards. This is a golden path applied to deployment configuration, and it is one of the highest-impact things a platform team can build.

![Engineering team collaborating around a whiteboard planning platform architecture and developer workflows](https://images.unsplash.com/photo-1522071820081-009f0129c71c?w=800&q=80)

### Developer Experience Metrics

You cannot improve what you do not measure. The DORA metrics (deployment frequency, lead time for changes, change failure rate, and mean time to recovery) are the industry standard for measuring engineering performance, and your IDP should make them visible. But DORA metrics alone do not capture the developer experience.

Track these additional metrics to measure your IDP's impact:

- **Time to first deploy:** how long does it take a new developer to ship their first change to production? This measures onboarding effectiveness.

- **Time to provision:** how long does it take to get a new environment, database, or cloud resource? This measures self-service effectiveness.

- **Service creation time:** how long does it take to go from "I need a new service" to "the service is running in staging"? This measures golden path effectiveness.

- **Platform adoption rate:** what percentage of new services are created through the platform vs. manually? Target 80% or higher within six months of launch.

- **Developer satisfaction (DevEx survey):** quarterly surveys measuring developer satisfaction with tooling, workflows, and infrastructure. Use a consistent scale so you can track trends over time.

Build a dashboard that shows these metrics and make it visible to engineering leadership. Concrete data is the most powerful tool you have for securing continued investment in the platform. When you can show that time-to-first-deploy dropped from 8 days to 2 days after launching the IDP, the budget conversation for your next phase of work becomes much easier.

## Team Adoption: The Make-or-Break Factor Most Platform Teams Ignore

You can build the most technically impressive IDP in the world, and it will fail if developers do not adopt it. Adoption is not a marketing problem or a mandate problem. It is a product problem. You need to earn trust incrementally, reduce friction relentlessly, and resist the urge to force adoption through policy.

Start with a pilot team. Pick one team that is vocal about infrastructure pain, ideally a team working on a new project that needs to spin up several new services. Work closely with them during the first four to six weeks. Sit in their standups. Pair with their developers when they use the platform. Watch where they get confused, where they get frustrated, and where they work around the platform instead of through it. Every workaround is a bug in your product.

Ship improvements weekly. The pilot team should see the platform getting better in response to their feedback every single week. This builds trust. It signals that the platform team is responsive, that feedback matters, and that the IDP is a living product, not a mandated tool that will never change. The fastest way to kill adoption is to launch a v1, disappear for three months, and come back with a v2 that still does not address the feedback developers gave on day one.

After the pilot team is productive and happy (measure this with the metrics from the previous section), expand to two more teams. Then four. Then open it to the whole organization. Each expansion phase should include lightweight onboarding: a 30-minute demo, a getting-started guide, and a dedicated Slack channel where developers can ask questions and report issues. Do not dump a Confluence page on 50 developers and call it a rollout.

### Common Adoption Mistakes

- **Mandating adoption before the platform is ready:** forcing developers onto a half-built platform breeds resentment. Let the quality of the platform drive adoption organically for the first six months. Policy mandates should come later, after the platform has proven its value.

- **Building in isolation:** platform teams that do not talk to their users build the wrong thing. Embed a platform engineer with a product team for one sprint per quarter. The insights are invaluable.

- **Optimizing for the platform team's convenience instead of the developer's experience:** your catalog schema, your golden path parameters, your self-service forms should all be designed from the developer's perspective. If a developer needs to fill out 15 fields to create a database, you have optimized for your backend, not their workflow.

- **Ignoring the "last mile" of developer experience:** the platform provisions a database, but the developer still has to manually copy the connection string, update three config files, and restart their local environment. The last mile matters. Automate it.

The best leading indicator of adoption success is organic word-of-mouth. When developers start recommending the platform to teammates unprompted, when new hires hear about it in their first week from their buddy (not from an onboarding document), you have crossed the adoption threshold. Everything before that point is iteration.

## Implementation Timeline, Cost, and Getting Started

Building an IDP is a multi-phase effort. Trying to do everything at once is the surest path to delivering nothing. Here is a realistic timeline based on what we have seen work across dozens of [engineering teams](/blog/how-to-build-engineering-team) of varying sizes.

### Phase 1: Foundation (Weeks 1 to 6)

- Developer experience research and pain point mapping (Week 1 to 2)

- Tool selection and initial setup of Backstage or Port (Week 2 to 3)

- Service catalog population with automated scanning (Week 3 to 4)

- First golden path template for your most common service type (Week 4 to 6)

- Pilot team onboarding and feedback collection (Week 5 to 6)

### Phase 2: Self-Service (Weeks 7 to 12)

- Crossplane or Kratix setup for infrastructure provisioning (Week 7 to 9)

- Two to three self-service actions: database provisioning, environment creation, secret management (Week 9 to 11)

- CI/CD integration showing deployment status in the portal (Week 10 to 11)

- Second pilot team onboarding, iterate on feedback (Week 11 to 12)

### Phase 3: Scale (Weeks 13 to 20)

- Additional golden paths covering 80% of service creation patterns (Week 13 to 15)

- Kubernetes deployment abstractions with internal Helm charts or Score (Week 15 to 17)

- Developer experience metrics dashboard (Week 17 to 18)

- Organization-wide rollout with onboarding program (Week 18 to 20)

### Cost Estimates

The infrastructure cost of running an IDP is modest. A Backstage deployment on a small Kubernetes cluster or a single EC2 instance costs $50 to $150 per month. Crossplane runs as controllers inside your existing Kubernetes cluster with negligible additional resource usage. The real cost is engineering time. Budget 0.5 to 1.0 dedicated platform engineers for Phase 1 and 2, scaling to 1 to 2 platform engineers for Phase 3 and ongoing maintenance. For a team that does not have a dedicated platform engineer, Port's managed offering eliminates the maintenance burden at a per-developer licensing cost.

If you are using Backstage, the total tooling cost for a 30-developer organization is roughly $150/month for hosting plus the engineering time investment. With Port, the total cost is approximately $750 to $900/month for 30 developers on the growth plan, but with significantly less engineering time required for setup and maintenance. Both options deliver ROI within the first quarter when measured against the developer productivity gains outlined earlier in this guide.

The biggest risk is not cost. It is building a platform that does not match what your developers actually need. That is why the research phase in Step 1 is non-negotiable. Skip it, and you will spend three months building something that requires a rewrite. Invest two weeks in understanding your developers, and every subsequent week of platform work compounds in the right direction.

If you are ready to build an IDP for your team but want an experienced partner to accelerate the process, avoid common pitfalls, and get to production faster, we have helped teams from 15 to 200 engineers design and ship platforms that developers actually adopt. [Book a free strategy call](/get-started) and we will map out the right approach for your organization.

---

*Originally published on [Kanopy Labs](https://kanopylabs.com/blog/how-to-build-an-internal-developer-platform)*