Internal developer portal MVP: how do I get started

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. 

Consider the final product

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

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.

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:

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.