Blog
/
/
Internal developer portal: how do I get started?
Internal Developer Portal

Internal developer portal: how do I get started?

May 6, 2024
Sooraj Shah
Internal Developer Portal

Intro

So you’ve opted for a microservices architecture, you’re using more and more dev tools that solve different problems, you’re shifting left, and you’re adopting a cloud native approach. 

These are all major steps forward. But any concoction of these steps is also (unintentionally) breaking the developer experience.

To exploit the benefits of these major steps while improving the developer experience, you’ve chosen platform engineering and considered using an internal developer portal. But how do you get started with a portal?

Get the focus right

It’s tempting for platform engineering teams to want to:

  • Build an engineering-centric portal 
  • Provide a jam-packed information service catalog to users that accurately reflects services, infrastructure and architecture
  • Expect adoption to occur quickly, without any deep consideration of the behavioral changes required of developers 

But to really maximize the benefits of a portal and prove to developers, SMEs and executives that the portal is right for them, platform engineering teams should:

  • Build a portal that reduces complexity for developers while maintaining engineering standards, by thinking about what needs to be abstracted for developers rather than showing all information in one place
  • Acknowledge that they need to deliver a product-like experience and therefore focus on jobs to be done (using the best possible solution to accomplish a specific task) and user stories, to truly understand what the portal needs to do
  • Communicate and gain feedback from stakeholders on their pain points and needs, and consider how the developer portal will actually be used
  • Acknowledge that building and adoption can take time and that a portal and indeed any platform engineering effort is a result of continuous iteration and improvement

With all of that in mind, their key questions are what should I build first and how can I get a working portal up and running swiftly?

You need an MVP

Focusing on a whole range of features and use cases creates complexity and onboarding challenges. It also leaves developers overwhelmed and disengaged. That’s why it makes sense to begin with a minimal viable portal (MVP) first. The MVP is a smaller subset of developer routines that cover actual use cases in the organization, servicing real developer needs, which can then be tested and iterated on.  

The MVP and each subsequent step, is prepared in quick sprints, each of which should be soft-launched as quickly as possible. Once the MVP is ready, you can add more developer routines, growing the functionality of the portal, and, as a result, driving additional adoption, until you are ready for general availability.

Another interesting concept is Thinnest Viable Platform - as defined in Team Topologies, a TVP is a careful balance between keeping the platform small and ensuring that the platform is helping to accelerate and simplify software delivery for teams building on the platform. If you don’t have a fully developed internal developer platform, a TVP can help define what a Portal MVP needs to be on top of it.

Note that the MVP is not an arduous process; it is the best option for getting started quickly with Port. 

Internal Developer Portal: How Do I Get Started?

Consider the final product

Internal Developer Portal: How Do I Get Started?
Click to enlarge image

A fully-fledged internal developer portal would include every use case found in the above image - covering everything from planning to post-production ops. It is an end-to-end developer experience covering the entire SDLC. This vision means a developer has everything they need in one place, they don’t need to keep switching between their ever-growing list of tools. The definition and implementation of planning to post production ops requires thought, a product mindset and needs careful attention to gain adoption.
But, as marked in the image above, an MVP can cover the following and be quite useful:

  • Letting developers find service data
  • Scaffold a new service
  • Deploy a developer environment
  • Promote a service to production
  • Rollback a service

These five points - one software catalog and four self-service actions are a robust MVP that would immediately value across all stages of the SLDC.
The portal should touch all of the steps throughout this journey.
This will mean developers:

  • Don’t need to context switch as they can use one tab for all tools (except for git or their CDE)
  • Know what the golden paths are
  • Are served infrastructure and K8s data in a way that’s abstracted and personalized to them
  • Don’t need to know tools and technologies that aren’t core to their work
  • Can self-serve most actions with a golden path with no need to tap into tribal knowledge or send a ticket to devops

Pick your user stories

Now that you’ve considered what your final picture may look like. You can get to work on your MVP by picking the parts of the planning to post-production ops journey that you want to improve. 
Pick the use cases that you know are:

  • in high demand
  • are easy to implement and 
  • of high value
Internal Developer Portal: How Do I Get Started?


The perfect MVP use case should tick all three boxes. 

In addition, you will want to consider:

  • The problem severity with the existing way of doing things
  • The potential impact on developers of using the portal instead
  • Success metrics which you’ll use to determine whether the user story choices were the right ones

You can find out what these use cases are and the impact they have on developers through quantitative and qualitative feedback from developers. (Note: if you’re looking for a survey you can use, you can get in touch with us here and we’d be happy to send it over to you).
Then, you should compile this information in an accessible way, and track the progress of each user story.

Internal Developer Portal: How Do I Get Started?
Click to enlarge image

Once you’ve picked your user stories, you can combine relevant user stories into sprints. For example, a group of user stories can all be part of the ‘bring features to production’ sprint. 

Consider sprint action items

Lets say your sprint includes creating self-service actions for: running a deployment for a service, promoting to production and rollback, you can ensure you’ve got the relevant docs, which in this case can be found here:

1. Run a deployment or a Rollback for a service using ArgoCD | Port

2. Promote Deployment to Production | Port

Then, you can consider the wider implementation plan:

Internal Developer Portal: How Do I Get Started?

2 steps to creating an MVP of your developer portal

You may be tempted to focus on only creating a service catalog for your MVP. While you would be right on focusing on this, you should equally focus on self-service actions because these will move the needle the most when it comes to reducing friction and wait times. 

1. Form an initial software catalog

You can populate the initial software catalog using any one of Port’s integrations, including GitHub, which is the most commonly used for the initial setup. If we take GitHub as an example, you can bring in raw GitHub data into the catalog.

To do this, you use blueprints in Port, which define the metadata associated with the software catalog entities you choose to add to your catalog. Blueprints support the representation of any asset in Port, such as microservices, environment, package, cluster, databases, etc. Once blueprints are populated with data - in this case, from GitHub - the entities are discovered automatically and formed within the software catalog.

This initial catalog gives developers visibility of the entire tech stack, so they can understand who the owners are of different services, access documentation of each service through Port, keep track of deployments and changes made to a service, and more.

Check out our guide to building a software catalog here

2. Create your first self-service action

Self-service actions are created and managed in the self-service page of your portal. You simply click the + New Action button in the top right corner. Choose the blueprint for which you would like to create the action then you:

1. Setup the action’s frontend

Decide what the name of your action will be, its icon and the inputs you would like the developer to see/select from in the self-service form.

2.Setup the backend

Then you set up the logic responsible for handling the action after execution. 
This could be anything from:

  • Creating a pull request for a IaC file with injected values
  • Triggering a Github Workflow or customer Python/Bash script
  • Making an API call to one of your internal APIs.

3. Set guardrails

Add manual approvals, policies, and TTL to actions to ensure that organizational standards are met. 
Overall, the platform engineer can control what the developer sees and can do, as well as permissions. As a result, developers can perform actions on their own within a defined flow, with the necessary guardrails in place. 
Checkout our guide to create self-service actions here

Port’s Takeaway 

When building a portal, it’s important to consider how a portal can improve your planning to post-production ops journey in the long run. For the MVP, the focus should be on the use cases which will be easiest to implement and provide the most value by helping you to overcome issues. 

That way, you’ll be considering your developers’ needs first rather than focusing on how the pillars of the portal (software catalog, self-service, scorecards) can be used to benefit the organization. In other words, it’ll save you from beginning with things that ‘sound good’ and actually help you to gain tangible benefits by working on the areas of development that need to be prioritized. The portal MVP should demonstrate how much of a change the portal can provide to the entire team - so starting with the things that are clearly giving developers trouble now is a no brainer.  

{{cta}}

Book a demo right now to check out Port's developer portal yourself

Book a demo
{{jenkins}}

It's a Trap - Jenkins as Self service UI

Read more
{{gitops}}

How do GitOps affect developer experience?

Read more
{{ebook}}

It's a Trap - Jenkins as Self service UI. Click her to download the eBook

Download eBook
{{cyberark}}

Learning from CyberArk - building an internal developer platform in-house

Read more
{{dropdown}}

Example JSON block

{
  "foo": "bar"
}

Order Domain

{
  "properties": {},
  "relations": {},
  "title": "Orders",
  "identifier": "Orders"
}

Cart System

{
  "properties": {},
  "relations": {
    "domain": "Orders"
  },
  "identifier": "Cart",
  "title": "Cart"
}

Products System

{
  "properties": {},
  "relations": {
    "domain": "Orders"
  },
  "identifier": "Products",
  "title": "Products"
}

Cart Resource

{
  "properties": {
    "type": "postgress"
  },
  "relations": {},
  "icon": "GPU",
  "title": "Cart SQL database",
  "identifier": "cart-sql-sb"
}

Cart API

{
 "identifier": "CartAPI",
 "title": "Cart API",
 "blueprint": "API",
 "properties": {
   "type": "Open API"
 },
 "relations": {
   "provider": "CartService"
 },
 "icon": "Link"
}

Core Kafka Library

{
  "properties": {
    "type": "library"
  },
  "relations": {
    "system": "Cart"
  },
  "title": "Core Kafka Library",
  "identifier": "CoreKafkaLibrary"
}

Core Payment Library

{
  "properties": {
    "type": "library"
  },
  "relations": {
    "system": "Cart"
  },
  "title": "Core Payment Library",
  "identifier": "CorePaymentLibrary"
}

Cart Service JSON

{
 "identifier": "CartService",
 "title": "Cart Service",
 "blueprint": "Component",
 "properties": {
   "type": "service"
 },
 "relations": {
   "system": "Cart",
   "resources": [
     "cart-sql-sb"
   ],
   "consumesApi": [],
   "components": [
     "CorePaymentLibrary",
     "CoreKafkaLibrary"
   ]
 },
 "icon": "Cloud"
}

Products Service JSON

{
  "identifier": "ProductsService",
  "title": "Products Service",
  "blueprint": "Component",
  "properties": {
    "type": "service"
  },
  "relations": {
    "system": "Products",
    "consumesApi": [
      "CartAPI"
    ],
    "components": []
  }
}

Component Blueprint

{
 "identifier": "Component",
 "title": "Component",
 "icon": "Cloud",
 "schema": {
   "properties": {
     "type": {
       "enum": [
         "service",
         "library"
       ],
       "icon": "Docs",
       "type": "string",
       "enumColors": {
         "service": "blue",
         "library": "green"
       }
     }
   },
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "system": {
     "target": "System",
     "required": false,
     "many": false
   },
   "resources": {
     "target": "Resource",
     "required": false,
     "many": true
   },
   "consumesApi": {
     "target": "API",
     "required": false,
     "many": true
   },
   "components": {
     "target": "Component",
     "required": false,
     "many": true
   },
   "providesApi": {
     "target": "API",
     "required": false,
     "many": false
   }
 }
}

Resource Blueprint

{
 “identifier”: “Resource”,
 “title”: “Resource”,
 “icon”: “DevopsTool”,
 “schema”: {
   “properties”: {
     “type”: {
       “enum”: [
         “postgress”,
         “kafka-topic”,
         “rabbit-queue”,
         “s3-bucket”
       ],
       “icon”: “Docs”,
       “type”: “string”
     }
   },
   “required”: []
 },
 “mirrorProperties”: {},
 “formulaProperties”: {},
 “calculationProperties”: {},
 “relations”: {}
}

API Blueprint

{
 "identifier": "API",
 "title": "API",
 "icon": "Link",
 "schema": {
   "properties": {
     "type": {
       "type": "string",
       "enum": [
         "Open API",
         "grpc"
       ]
     }
   },
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "provider": {
     "target": "Component",
     "required": true,
     "many": false
   }
 }
}

Domain Blueprint

{
 "identifier": "Domain",
 "title": "Domain",
 "icon": "Server",
 "schema": {
   "properties": {},
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {}
}

System Blueprint

{
 "identifier": "System",
 "title": "System",
 "icon": "DevopsTool",
 "schema": {
   "properties": {},
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "domain": {
     "target": "Domain",
     "required": true,
     "many": false
   }
 }
}
{{tabel-1}}

Microservices SDLC

  • Scaffold a new microservice

  • Deploy (canary or blue-green)

  • Feature flagging

  • Revert

  • Lock deployments

  • Add Secret

  • Force merge pull request (skip tests on crises)

  • Add environment variable to service

  • Add IaC to the service

  • Upgrade package version

Development environments

  • Spin up a developer environment for 5 days

  • ETL mock data to environment

  • Invite developer to the environment

  • Extend TTL by 3 days

Cloud resources

  • Provision a cloud resource

  • Modify a cloud resource

  • Get permissions to access cloud resource

SRE actions

  • Update pod count

  • Update auto-scaling group

  • Execute incident response runbook automation

Data Engineering

  • Add / Remove / Update Column to table

  • Run Airflow DAG

  • Duplicate table

Backoffice

  • Change customer configuration

  • Update customer software version

  • Upgrade - Downgrade plan tier

  • Create - Delete customer

Machine learning actions

  • Train model

  • Pre-process dataset

  • Deploy

  • A/B testing traffic route

  • Revert

  • Spin up remote Jupyter notebook

{{tabel-2}}

Engineering tools

  • Observability

  • Tasks management

  • CI/CD

  • On-Call management

  • Troubleshooting tools

  • DevSecOps

  • Runbooks

Infrastructure

  • Cloud Resources

  • K8S

  • Containers & Serverless

  • IaC

  • Databases

  • Environments

  • Regions

Software and more

  • Microservices

  • Docker Images

  • Docs

  • APIs

  • 3rd parties

  • Runbooks

  • Cron jobs

Check out Port's pre-populated demo and see what it's all about.

Check live demo

No email required

Contact sales for a technical product walkthrough

Let’s start

Open a free Port account. No credit card required

Let’s start

Watch Port live coding videos - setting up an internal developer portal & platform

Let’s start

Check out Port's pre-populated demo and see what it's all about.

(no email required)

Let’s start

Contact sales for a technical product walkthrough

Let’s start

Open a free Port account. No credit card required

Let’s start

Watch Port live coding videos - setting up an internal developer portal & platform

Let’s start

Let us walk you through the platform and catalog the assets of your choice.

I’m ready, let’s start