5 tips for implementing an Internal Developer Portal in your company

| 6 minutes read

More and more companies are adopting the Agile approach and DevOps paradigm to accelerate and improve their software development. Even though some software lifecycle processes have been simplified and speeded up, companies need new tools and technologies in order to put DevOps methodologies into practice – such as task managers, automated pipelines, and testing systems. 

As the number of technologies and tools used within the company increases, there is the risk that developers, especially those with less knowledge of the company’s technology stack and developed products, will waste time searching for the resource they need, developing from scratch artifacts that are already available in the company’s software assets, and adapting to the flexibility constraints of the infrastructure.

Tools that were supposed to speed up work could end up slowing it down in a significant way. To avoid this danger, a radical perspective shift is required: you should start abandoning the infrastructure‑centric vision, and instead, you should put the Developer Experience (or DevX) at the center of the deployment process. The Internal Developer Portal (IDP, or Internal Developer Platform) was created to meet this need. The IDP is a single portal that brings together all the tools and technologies available and used within the company. In this way, development teams can focus on developing functionality related to the company’s core business, instead of wasting energy and efforts developing from scratch functionalities that are already built, or that can be developed faster thanks to templates and libraries already available.

What is an Internal Developer Portal?

Before delving into the features of an Internal Developer Portal, let’s highlight the differences from an External Developer Portal (EDP). An EDP helps developers outside the organization, providing them all the information and resources they need to properly integrate their systems with the organization’s ones. Usually the integration is made thanks to some APIs, so, often the EDP is actually the API Portal. The IDP has an API catalog for internal APIs, but it also aims to streamline the software development and encourage the sharing and reuse of components within the company

Once all components are standardized by the team responsible for the Internal Developer Portal, these components will be available to development teams, which will only have to integrate and configure the components according to their own needs. 

The Internal Developer Portal provides enhanced visibility, traceability, auditability, and observability across the whole DevOps cycle. Design, infrastructure, monitoring, deployment, documentation: every stage benefits from this tool. To provide maximum support to development teams, the Internal Developer Portal should contain:

  • A well‑documented API catalog;
  • A marketplace of services (or microservices) that execute common functionalities – already tested and ready for reuse. The marketplace should always be enriched and maintained over time to meet evolving needs of developers;
  • Direct access to all development and management tools used and usable within the company;
  • Complete documentation of the infrastructure;
  • Guidelines and best practices for new components development;
  • Monitoring tools.

In this way, adopting an Internal Developer Portal allows developers to self‑sourced the available technology, improves governance – because reused components have already been tested and validated – and encourages knowledge sharing.

How an Internal Developer Portal can help your organization

An Internal Developer Portal allows you to improve the productivity of all development teams within your company, regardless of how it is organized. If your organization has already adopted a DevOps methodology,  aims to build its own Digital Integration Hub, and it is organized into Feature Teams, the Internal Developer Portal is a tool that ensures you get the most out of them. 

Since an IDP should continually evolve with the business, below are our recommendations and suggestions for implementing an Internal Developer Portal that helps your organization at every stage of the software lifecycle.

1. Infrastructure: manage clusters transparently

Ops teams and development teams have very separate areas of expertise and usually prefer to stay in their own field – with the exception of any DevOps figures that can work in both areas. This is proven by the fact that usually, when a new infrastructure has to be implemented, it is easy for the component creation and management phase, which require the cooperation of the two teams, to act as a bottleneck and slow down the whole process.

An Internal Developer Portal should provide developers with ready‑to‑use and standardized components: this way, developers can install clusters, manage environment variables, and update the infrastructure independently. Log audits should be centralized for the entire infrastructure, and you should have a single authentication and authorization system. In addition, it is recommended to automate some aspects like the following:

  • Infrastructure scaling, both horizontal and vertical
  • Backup systems
  • Monitoring systems
  • Alarm systems

An Internal Developer Portal also provides significant resource and cost savings, by: 

  • Monitoring all aspects of the software lifecycle, you can know if there are unused resources that can be turned off or reused for other systems. 
  • Sharing the infrastructure according to the multi‑tenancy approach, which allows distributing also the infrastructure costs.

2. Design & Reuse: 100% control of released software 

When designing the infrastructure of a cloud‑native application, it is important to determine which components you want to be reusable by other applications. To foster this operation, an Internal Developer Portal should make developers autonomous during configuration, testing, API and event exposure. In addition, after business standards have been defined, developers will also be able to independently define:

  • Security
  • Services version strategies
  • Service aggregates and product versions

This can be facilitated by building a Service Catalog that provides services, APIs, and source code that are already tested and ready for reuse.

3. Deploy: no bottlenecks in deployment process

When it comes to deploying, developers should be able to independently access runtime environments. With the IDP, developers are autonomous and free from the concern of managing clusters and infrastructure: they just need to select the environment and deploy, without having to wait for the manual configuration by the Ops department. This allows developers to:

  • tag deployments;
  • make dry run deployments to preview the new development before actual deployment;
  • run rollbacks in case of problems;
  • launch automated tests.

In this way, developers are totally independent of other teams and have full traceability of each deployment’s content, knowing by whom it was executed and when.

4. Monitor: check the health of your applications

By centralizing every tool and artifact in the Internal Developer Portal, you can create a single dashboard to monitor the status of all services. You can also create automation that leads to the creation of other dashboards and alerts, which are critical especially for applications that run 24/7. Logs are aggregated and centralized so that developers always have them available: this way, they don’t have to request them from other departments and they can act in a timely manner if something goes wrong. Business metrics are also easily visible and available, as well as all security‑related alerts are gathered in one place: this allows easier and more effective monitoring. 

5. Documentation: knowledge sharing

An Internal Developer Portal should also provide a space for documentation to ensure that knowledge is preserved and shared. Documentation is thus gathered in one place and made available by the IDP: developers don’t need to access many different tools – such as Wikis, shared folders, dedicated platforms – to find and consult it.

Since documentation is made by developers for developers, the best way to encourage writing and usage is to adopt a Docs as Code approach. This approach states that documentation is part of the software, so it should be drafted and maintained using the tools and methodologies that developers use for their daily code activities. In general, documentation should be Git‑based, to facilitate collaboration and manage versioning, and should be written in a text‑based markup language, such as Markdown. 

Automation can enhance other key functionalities: it is possible to create automated documentation starting from API specifications and event schemas, as well as it is possible to collect in one place the README file of each microservice, to have a complete overview that updates automatically whenever a single file is edited. 

It is always very useful to create guides, examples, best practices to accelerate the onboarding of new team members and to standardize development practices within the company. Lastly, inserting up‑to‑date architectural diagrams allows developers to be always aligned.

Conclusions

By adopting Agile methodology and the DevOps paradigm, along with an organization in Feature Teams, companies can dramatically improve cloud‑native software development. However, to prevent the massive deployment of new development tools and technologies from slowing down the work of development teams instead of speeding it up, it is necessary to put developers and their experience at the center. To improve DevX, the most effective tool is the Internal Developer Portal (IDP), a single portal that collects all available services and tools in one place. The Internal Developer Portal streamlines the development process at every stage, starting from design and ending with documentation.

However, creating an IDP from scratch can be a long and expensive process, because, in order to maximize its effectiveness, it is necessary to develop many different and interconnected functionalities. There is a risk that you could invest all the time you’ve saved by adopting new technologies and methodologies in creating and maintaining the IDP, rather than reinvesting this time to increase productivity. The solution is to adopt a ready‑made Internal Developer Portal such as the one provided by Mia‑Platform* to avoid infrastructure concerns, and focus on customizing it to the needs of the business.


The article was written by QZR srl, your friendly development team.

Leave a Reply