How to streamline application scaffolding with internal developer portals

An internal developer portal provides developers with an automated method for creating a new application, in a way that aligns with organizational standards.

Background

As a Solutions Engineer at Port, I hear about the main issues our customers’ platform teams face and what drives them to explore the space of internal developer portals.
In every session in the last few months, we keep hearing the same things: 

•  Developers want to be able to create a new microservice/application, from a standardized template, instead of creating it manually from scratch (like they do today).
• R&D Managers want to make sure all microservices are aligned and set to their organizational standards in the scopes of CI/CD, security, and documentation.
• When working on a new application, we want a way to create the initial application skeleton, instead of opening a ticket to the Platform team to create an Argo application, create Cloud resources, and more.
• R&D Managers want to provide golden paths for developers in their microservice development cycle by providing an automated way for developers to act without assistance while meeting company standards.

It all boils down to the same issue: Scaffolding a new application. 
A common approach to addressing this process is to create a new repository from a template. Although that might sound quite straightforward, scaffolding a new application requires thoughtful consideration. 

The problem

In essence, we always see the same kind of problem -  manually building microservices creates a real mess for development teams. 

• Without a template, developers must put together microservices piece by piece, dealing with manual configurations and infrastructure setup, which are out of their comfort zone. This leads to things getting jumbled up – from inconsistent coding practices to challenges in meeting organizational standards. 
• Relying on traditional ticketing systems for infrastructure creation adds to the frustration, causing delays and slowing down the development process. 
• For R&D Managers, it's tough to guide developers smoothly through these complexities, affecting innovation and overall productivity. It's not just a hassle; this translates into tangible business pain, impacting timelines and the efficiency of the entire development workflow.

The Developer POV

Let’s try looking at this through a developer's eyes in a large organization. They need to develop a new microservice as part of a new ticket created by the PM. They have all the implementation steps in mind

• the language they’ll use
• how they can make it generic to support different webhooks
• how they’ll write the most beautiful code.
  

Are they ready? You wish!

First, you would want to be able to check if someone has already written code you can use.
Then, you need to:

• Create a new repository with standardized README and folder hierarchy  - (Do you have standards? What does a perfect readme file look like?)
• Create a Kafka topic - Write an IaC code section to spin up a Kafka topic alongside your service or if in a larger corporate organization - open a ticket to the platform engineering team which means I have 1-3 days to wait.
• Create a boilerplate for tests & configure the CI process
• Configure SonarCloud scans on every merge to “main"
• Create a new ArgoCD app and connect it to your new service by opening a pull request to the Argo management repository (You may have heard of Argo but you would need to learn about it now to set it up well)
• Deploy the initial application to a test environment

This is a lot of work without even considering the actual coding. It also requires some in-depth knowledge, at least in order to comply with the standards of the specific engineering organization. 
All this not only adds to the tasks at hand but also makes it more challenging to get everything done smoothly. Besides that, it increases developers’ cognitive load.

‍The Platform Engineer POV

Let’s switch to the eyes of a Platform engineer. 
For them, engineering standards are key to ensuring microservices remain organized and consistent.
A platform engineer manages hundreds of microservices and faces some recurring problems: 

• Different Repository Structures:

Repositories have various structures, making it hard to search for information when working on different microservices.

• Missing Documentation:

Some repositories lack essential documentation, making it harder to understand  and maintain them.

• Unprotected repository branches: 

These allow for uncontrolled updates, compromising the security and consistency of the development process.

• Deployment Setup Issues:

Deployments across microservices are inconsistently configured, leading to potential deployment issues.

• Outdated Versions:‍

Some microservices have outdated versions of packages, cloud resources, and more. Causing compatibility and security concerns.
‍

The above problems make scaffolding a new application a much more thorough and complex operation. It is almost impossible to expect many different teams to comply with the standards of their company without any guidance or automation.

The solution

Automating scaffolding of a new service

Here's a straightforward solution: give developers a ready-to-use setup for new applications, and provide it through an internal developer portal. 
It's more than just a basic repository; this automation should provide essential resources: 

• A ready-to-use repository
• An easy-to-follow pipeline
• A Terraform request for a new database
• An ArgoCD app
• A simple Kubernetes deployment
• A new Lambda function linked to the repository, and 
• Pre-configured S3 Buckets. 

These ready-made paths help developers stick to standards effortlessly, ensuring consistency without any complications. 

Here's your easy start guide for launching this process within your team:

Step 1 - Define the application suite

As a solutions expert at Port, I see this same problem A LOT, yet I can’t find two customers with the exact same standards and scaffolding processes.
So, platform engineers need to ask an important question to determine what developers need in the packaging of a new application:

“What can we provide to developers to make sure they can focus on the thing they are best at - writing code?”

The answer varies from one organization to another, with their very specific processes, standards etc, but it is likely to be things that engineers can automate or template for developers to provide them with autonomy. 

By communicating directly with developers and gaining their feedback on their current pain points and what they’d like to see, engineers would be embracing a product management approach. This helps platform engineers to ensure they don’t just solely focus on the engineering and architecture, and rather apply product thinking as to what they want to offer in it. 

In this hypothetical example, we’ll say that scaffolding a new application will include creating a repository, configuring CI/CD, and creating cloud resources with Terraform.

‍Step 2 - Decide what inputs should be provided by the developers

In this step, it's crucial to identify which parameters should be dynamically defined by developers. The aim is to abstract complexity, asking only for inputs that genuinely matter for the customization of the scaffolding process. Think of this as focusing on the "what" rather than the "how," allowing developers to specify essential aspects of their projects without getting bogged down in implementation details.

Here is an example of a ‘basic common inputs’ list:

• Service name 
• Description
• Language
• Database
• Create Kafka Topic?
• Create Database?

‍Step 3 - Create the scaffolding automation

The scaffolding logic takes the inputs from developers and automates the setup of the new project. This includes creating the repository, setting up the infrastructure, and configuring the necessary tools and environments. The aim is to eliminate manual steps.

In this specific scenario, we achieve automation using a GitHub Action.

‍

As seen in the diagram, the automation will interact with the different platforms, using the specific permissions needed, managing resources using the company's best practices, and based on the dynamic inputs provided by the developer.

‍Self Service with an Internal developers portal

So far, we have established a great automation for creating a new application. But that alone might not be enough. 

Managing application creation with GitHub actions can be a challenging effort for developers, highlighting the need for a centralized solution. A self-service portal, designed with an intuitive user interface, detailed role-based access control (RBAC), robust input validation, and a customized approval process can significantly simplify the application setup process without any additional development effort.

‍How does it work with Port? 

Port supports long-running and asynchronous actions and shows developers the run logs they need.
A user triggers a self-service action in the developer portal UI;
A payload that includes the user inputs and relevant action metadata is sent to the desired GitHub workflow.
A job is triggered and the user gets a continuous indication about its progress.

‍Using Port’s software catalog to visualize the application creation

With Port, you can create a customized self-service experience that exactly matches the scaffolding flow we built in the above scaffolding logic. In addition, once the application is created, we can visualize all the created resources (Argo application, cloud resources, Sonar scans) in a single pane of glass in the context of the related application. That way, the whole process and its outputs are reflected in every step for your developers.

Sounds complex?

Not with Port. 

Once it’s all set and done, the routine of creating a new application will be:

1. A developer signs in to Port, and clicks on the “Scaffold a new application” action in the Self-Service Hub:

2. The developer provides the relevant inputs for the scaffolding process in a customized form: 

3. The action is initiated, and the scaffolding process is reflected in Port including its status and logs:

4. Once my application is scaffolded, the developer can see it in the service catalog, connected to the relevant related resources - SonarQube issues, Argo application, RDS instance, S3 buckets and Kafka topics

5. The application and its related entities can also be visualized in a birds-eye graph view:

‍

So I’ve finished creating my application, I’m done right?

Not quite. The above process is the first step in ensuring standards are met from day 1 of your applications. Thereafter, you have to ensure standards are maintained. To do this, you can use the portal’s Scorecards to evaluate the maturity, production readiness, and engineering quality of your applications. See more here.

‍Concluding Thoughts:

Self-serving the scaffolding process of an application requires deep thinking and a product mindset. You must see it from the perspective of developers, and you must curate the experience they receive based on your organizational DNA. With Port, you can tailor the process to fit your culture and standards. By doing so, you ensure that developers have the best experience possible while keeping your guardrails in place.

‍Next steps: 

For more insights into scaffolding a new application, check out our step-by-step guide. 

Or try it yourself by signing up to Port, here.