Kong Enterprise 3.3 delivers enhanced security, usability, and platform reliability. Learn more
Engineering

How to Customize Your Kong Developer Portal

A developer portal is a storefront to your APIs (the products) that internal and external developers are trying to consume. 

The Kong Developer Portal provides a single source of truth for all developers to locate, access and consume services. With intuitive content management for documentation, streamlined developer onboarding and role-based access controls (RBAC), Kong’s Developer Portal provides a comprehensive solution for creating a unified developer experience. To take your developer experience to the next level, customers can customize the developer portal to reflect their organization’s unique branding.

In this post and video, we’ll walk through how easy it is to change the look and feel, create pages and add automation to the Kong Developer Portal.

1. Enable or Access Your Developer Portal

We’ll go to our Kong Manager to access our developer portal, a tool to configure the whole cluster from the Kong Gateway. If you haven’t already enabled your Kong Enterprise Developer Portal, follow our Kong documentation to complete this step and come back.

Kong Manager Workspaces

In the Workspace section of our Kong Manager, we’ll find the Dev Portal section. In this section, you can do many things, including setting up authentication, registration permissions, appearance and more. In this tutorial, we’ll be covering how to customize the Dev Portal appearance.

Kong Workspace

2. Update the Basic Appearance

The Dev Portal Appearance section of Kong makes it easy to change basic branding and colors.

All we have to do is click Upload Image and select the logo and favicon images we’d like to use from our device. Then, click Save Changes at the bottom of the page.

Kong Developer Portal Appearance

Let’s go back to our developer portal to see if it worked. We now have our dark blue Kong logo and the favicon with GRUCEO, our Kong gorilla, in our navigation tab.

Kong Developer Portal Favicon

Change Colors and Fonts

What else can we change in the appearance settings? We can change text colors, footer colors, button colors and fonts.

Kong Developer Portal Appearance Change Colors

Let’s say we want to have dark blue buttons that align with our corporate branding guidelines. We could either use the picker or color code for the exact matching button or button hover color. Then, we Save Changes again at the bottom of the page.

Kong Developer Portal Color Picker

3. Leverage Kong Dev Portal Editor Mode

Let’s look under the hood to see what more we can do beyond changing colors and logos. In the Dev Portal Editor, you can change the whole Dev Portal in every aspect.

Kong Developer Portal Editor Mode

Edit a Configuration File

We’ll start by going to the portal.conf.yaml file to see there is some text and data to be set.

Kong Developer Portal Edit Configuration File

We can, for example, change the name to Our Developer Portal. Reload again, and we’ll see “Our Developer Portal” in the page name.

Kong Developer Portal Navigation Name

Update the Theme Configuration File

In our theme configuration file, we can see the fonts, colors and images we’re using. Everything we did in step two is also available to update here in a YAML file. This is great for CI/CD users who want to speed things up by auto-generating those files.

Kong Developer Portal Theme Configuration File

We could extend what we did earlier by automating the reuse of our company color in different places with my_company_color and Save Changes.

Kong Developer Portal Theme Configuration File

In the Dev Portal Appearance section, we’ll now see “My company color” as an option to select from the UI.

Kong Developer Portal Custom Color Picker

Upload a New Specification

If we have a new OpenAPI or Swagger 2.0/3.0 that we want to upload, we would go to Editor Mode > New File + > File Type=spec > File Path=fun.yaml (the name of the file) > click Create File. Then, copy and paste the YAML file in the new spec. Once that’s saved, we’ll immediately see a live preview of everything we are changing.

Kong Developer Portal Upload New Specification

When we reload our Dev Portal, we’ll see the random facts YAML we just uploaded.

Kong Developer Portal Catalog

That’s the first glimpse of how we can change some content in our folder structure to have an OpenAPI file in place.

Let’s get under the hood now and look at how we can customize things in a little more detail.

Customize the Content

On our Dev Portal homepage, we have a “Built with Kong” welcome message. Let’s change that in the Content section of our Dev Portal Editor.

Kong Developer Portal Default

The files in the content section are available pages in our Dev Portal. There’s a login page, register page, index page, homepage page, etc.

Kong Developer Portal Edit Content

Let’s start by changing the title to Our Dev Portal and the tagline to Cool. Save Changes. And right away, we can see the change in the dev portal preview.

Kong Developer Portal Change Title and Tagline

How does Kong know how to render that file? The top of index.txt describes this. It’s using the layout called homepage.html, which leads us to the central concept of Kong: Every content is a YAML file like we see here. A template renders each of those YAML files. In this case, homepage.html.

Change Themes With HTML

Here we see some HTML for the homepage consisting of sub-templates, hero, catalog and clients. We can customize everything with HTML, JavaScript, CSS, etc.

Kong Developer Portal Change Theme HTML

Let’s edit the homepage hero by making the “Cool” tagline text as big as the title.

Kong Developer Portal Change Tagline Size

When customizing the Kong Dev Portal, we can create our own structures, templates, partials, layouts, etc. 

Alter Themes With CSS

Next, let’s change something that’s with CSS—the background image. In the site.css section of our styles assets, we’ll add this line and Save Changes.

.homepage-hero { background-image:url(https://your.server.example.com/background.jpg) !important;

Kong Developer Portal Edit CSS

If we reload our dev portal, we’ll see the customized banner is now uploaded.

Kong Developer Portal Customized

 

Create a Custom Content Template

Let’s get to the next level by creating our custom template and rendering it in our dev portal. We’ll add a news section to our dev portal. 

We’ll create a New File + in our content section in the editor, which we want to call news.yaml.

Kong Developer Portal Custom Content Template

And we’re getting here a skeleton of an entry.

Kong Developer Portal Custom Content Template Skeleton

Let’s flesh it out more. We’ll add a section called News. Underneath News, we’ll add a title: Our headline and our text: This is the news entry with everything… We’ll also add layout: news.html.

As we have done before, we can now choose our layout. Save Changes. Why has nothing happened? Instead of a news.html layout, we have a 404/Page Not Found.

Kong Developer Portal 404 Page Not Found

To create a layout, we can add a new file in our Themes folder. Create File.

Kong Developer Portal Create New Layout

To pull from our news.yaml file, we’ll add the following:

Kong Developer Portal Edit Content

Add New Page to Navigation

To add a News menu entry next to the catalog, just add it to the portal configuration file:

Kong Developer Portal Ad New Navigation Page

If we reload our Developer Portal, we’ll see the updated navigation:

Kong Developer Portal New Navigation News

4. Automate Kong Developer Portal Updates

We’re living in a CI/CD world and DevOps world, and so far, we have done everything using the browser as an interface, and we want to automate such changes and uploads. And here we come back to a very core principle of Kong, which is that everything in Kong is an API, which is also true for the whole developer portal.

Let’s look at the administration API running on 8001. We can remote control our installation completely. And there’s one endpoint called files.

http :8001/files

On files, we get the whole developer portal that we could see in our editor. All those files, contents, specs and themes are on this endpoint. 

We can go to http :8001/files/content/news.yaml for the news file we created.

Kong Developer Portal Automation

The Kong Developer Portal provides a full API to automate everything, including creating files, updating files and deleting files.

For example, we can use the API to upload another specification, like a movies specification.

Kong Developer Portal Automation Upload Spec

We can use the admin API /files and say, we want to upload it, we want to upload it to the specs folder. In our system, we want to call it movies.json. And then the contents we also want to get from that file.

http: 8001/files path=specs/movies.json contents=@movies.json

If we go back to our catalog, we’ll see that our movies API was automatically added.

Kong Developer Portal Automatically Add Catalog

Is there another way to create such files that would be more convenient for our web developers? Of course!

5. Use the Kong Developer Portal CLI

On our GitHub, there’s a Kong Developer Portal CLI. That’s a tool, which I already have installed, where you can remote control your portal using a CLI. To do so, as described down here, you want to clone the Portal Templates repo first to your machine.

cd
cd tmp
mkdir video
cd video
git clone https://github.com/kong/kong-portal-templates

Here we have the standard layout from the repo, which is the same one we started earlier today with the standard graphics and so on. They’re all in here.

Kong Developer Portal CLI

So if I go here and make an ls workspaces/default/content, you see there’s a portal Kong file, there are the contents like the index page, but still, the one which has been there from the beginning.

cd kong-portal-templates
ls
ls workspaces/default/content

Kong Developer Portal CLI

So if I look at that content/index page, that’s the standard one as it comes out of the box. That’s the one the system applied when we just created a new developer portal.

less workspaces/default/content/index.txt

Kong Developer Portal CLI Workspace Content

Now we can work with the portal CLI. I already had it installed on my machine. 

We want to use Portal to fetch an existing dev portal, and that’s the one from my default workspace. 

portal fetch default

And now, let’s have a look at the same file again. And we will notice our changes.

Kong Developer Portal CLI

6. Keep Your Preferred Editor

In your editor of choice, you can go ahead and see here all the contents–all about the page. What else do we do? We also did the content part with the news.yaml file. Or we did change the templates, themes and layouts. And we can change everything here.

Let’s portal deploy -W default to deploy back to Kong what I’m changing here in my local distribution. 

Let’s change some of the text on our homepage hero.

Kong Developer Portal Edit Homepage Visual Studio

And already, if I reload it here, you can see it’s updated.

Kong Developer Portal Custom

Why is that the case? When I said portal deploy, I also had this -W, which means I’m watching everything I’m doing locally, so we will immediately upload everything I change here. So the moment I saved the index file, it got uploaded to my dev portal. 

This is a very nice way for developers to create designs with their most beloved editors and frameworks. They can just work on their local machine and then have a live updating system up and running here.

Ready to Try Out Kong Dev Portal?

Contact Sales to start providing APIs as a product to your external teams to consume through a customized portal that leverages your existing CRM or repos as the source of truth.

Share Post

Subscribe to Our Newsletter!

    How to Scale High-Performance APIs and Microservices

    Learn how to make your API strategy a competitive advantage.

    June 20, 2023 8:00 AM (PT) Register Now