Kong Kong Tutorials, 11 Nov 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Customizing Kong Developer Portal

Description

The Kong Developer Portal provides a single source of truth for all developers to locate, access and consume services. In this 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.

Reach out to more about Kong Developer Portal: https://konghq.com/contact-sales

▬▬▬▬▬▬ TIMECODES ▬▬▬▬▬▬

0:00 Intro
0:12 Kong Dev Portal Out-of-the-Box
1:05 How to Access Your Kong Dev Portal
1:48 Upload Brand Images
2:35 Change Colors and Fonts
4:20 Edit a Configuration File
5:05 Update the Theme Configuration File
6:50 Upload a New Specification
7:54 Customize the Content
9:40 Change Themes With HTML
13:29 Alter Themes With CSS / Change Background Image
16:15 Create a Custom Content Template
20:30 Add New Page to Navigation
21:35 Automate Kong Developer Portal Updates
24:30 Use the Kong Developer Portal CLI
26:54 Leverage the Editor You Want
29:00 Conclusion

▬▬▬▬▬▬ LINKS ▬▬▬▬▬▬
❏ Read the blog version: https://konghq.com/blog/customize-kong-developer-portal/
❏ Kong Developer Portal Documentation: https://docs.konghq.com/enterprise/2.6.x/developer-portal/
❏ Kong Developer Portal CLI: http://github.com/kong/kong-portal-cli

#DeveloperPortal #DevPortal #KongGateway #APIGateway

A

Customizing-Kong-Developer-Portal.Mov, we will walk you today through how you can change the look and feel, how you can create.

A

Your own pages and how you can do also automate such things here in the developer, portal.

A

So, let's get started by having a first view on how to develop what looks like out of the.

A

Box., as you can see here on the screen right now., this is the kong developer portal just installed with an example theme where you can see, we.

A

Already have some logos, some colors attached,, some pre-packaged texts in there, and also.

A

Some openapi specifications as examples.

A

we'll use that developer portal,, which also has some more pages like the catalog, where.

A

You can find open api specifications, a lot in page and so on.

A

Now and change it to our corporate entity, step by step, to get more and more to look.

A

Like how we want to have it on our production, environment.

A

So what is the first step?? The first step will be that we want to change that logo up here,, and we also want to change.

A

The favicon,, according to our corporate standard.

A

So how can we do that?? So let's go over here to our kong manager.

A

The kong manager is our tool to configure the whole cluster,, so you will control all.

A

Data planes in your cluster from the gateway site,, you would see some statistics and so.

A

On. you can create one or multiple developer portals,, which we have done.

A

We have one running., you can have multiple of them.

A

and we will now change that dev portal here..

A

So we go to our own workspace so far and looking here in the dev portal section where you could.

A

Set up basic things like how we make authentication and we can ask for different registration.

A

Permissions and so on. all things we don't cover today.. We will look at appearance. appearance, as you can see, it's a nice click user interface, where you can just say, "oh,.

A

I want to change the branding,, the logo.".

A

So I just say, upload a logo..

A

I can just pick a logo from my pc here, and I want to have that kong logo here as the.

A

Background. and while I'm here also,, the favicon is not chosen so far,. So let me just upload an icon.

A

Here I already have prepared.

A

Going down here saying, save changes.

A

and going back to our dev portal, reloading the page, and we can see we now have here our.

A

Dark blue logo of kong in place,, and we also have now here the favicon with our kong gorilla.

A

In our navigation, tabs.

A

great., what else can you change here in the appearance, settings?

A

well,, you can always see. We gave you some color section.

A

You can change text colors,, you can change the footer color, some button, colors and so.

A

On, and also the fonts., so let's say, well,, we want to have the buttons.

A

The one here, according to our corporate standard,- and this is our dark blue.

A

Ok,, let's have that dark blue being set, and we have here this nice picker looking.

A

If we want to have the filling of the button primary,, we just click on here.

A

We can now do all the things here with a nice picker in here.

A

But if you already have that color code- and I got that from my marketing department,, I.

A

Can just set that up.

A

And now I have set that. safe changes. go ahead, reload, my page., and now it's dark blue. oh, still in green.. What else can we do?? Let's have a look again. oh,. We can also have to fill color if you are hovering over that button.

A

And once again, I got from my marketing department and I say,. We want to have another shade of.

A

Blue in here., so just setting it up in here with a lighter blue,, as you can see.

A

Save the changes, reload, the page.

A

And now we are having here this nice hover effect for the blue color.

A

So that's the very basic appearance settings we can do in here.

A

Colors, texts and fonts very easy,, as you can see.

A

So that's the starting point for your journey from customizing the kong design.

A

So, let's have now the first look under the hood. What we can do, more.

A

Typically,, when you want to design your dev portal,, you want to do more than just changing.

A

Some colors and logos.

A

and for this, we will have a look here at this section called editor.

A

In the editor, you can change the whole dev portal in every aspect.

A

We'll start here at the beginning., what do we have in here?? We do have here a section where we have a configuration file and you can see there are.

A

Some text to be set.. There are some other data which we'll look at on..

A

We can, for example,, say now. This is our developer. Portal.

A

That's the name.

A

just change that one.

A

Reload again and here,- and you can see now this is our developer. Portal.

A

Great., what else can we do here?

A

well, and we do have different sections.? We do have a section for the general portal settings.

A

And the next one is, we also have here a file of our configuration for the theme.

A

So we can look here at the theme down here.

A

And there's a theme conf file, where we can see exactly what we just did.

A

We can see the fonts,, we can see the colors and we also see the images where we just uploaded.

A

Our images in here., so everything that we just did, is also available here for a yaml file,, which is very great.

A

For ci/cd users, that you can just autogenerate those files in here and you can even extend.

A

That. you can just say,. I need to have here my own color.

A

Let's say it's my company color, so that you can reuse it later on in different places.

A

So, let's call it "my company, color" and here say: save changes.

A

And now we can reuse it in other parts of the template, and it's even now in the editor.

A

So if I go back in here,, you will see my company. Color could also be now be picked up. Here.

A

So it's a very extensible framework on what colors do we need?.

A

What are the typical colors so that there's no need to always have them hard coded somewhere,.

A

Built a list of the typical colors, go to your ci settings and find all of those colors.

A

And there. the next step,, let's change some of the contents.

A

Yeah, we see, we do have our developer portal,, what we have here: some apis, and we do have.

A

The catalog., so how do we change some contents here in our developer? Portal?.

A

Well, once again,, we go back to our manager, look at the editor and our different sections.

A

We already saw that portal on file.. We already looked a little bit in the themes, path.

A

We'll have a look at the content sections in a few seconds,, but now we want to upload.

A

A new specification to our system., so a new openapi or swagger 2.0 or 3.0.

A

How do we do that?, we just say new file., we just say it's a specification., so something about fun, and then we can simply copy and paste here. Our yaml file.

A

Save that change. and you already see, we're getting a live preview, a fully running, working live preview.

A

Here, on the right hand, side for everything we are changing.

A

and back to our developer portal, and we can just reload that one.

A

And we see now, there's our random facts.

A

Yeah. and the random facts...now we can see here all the facts., all these things in here.. So that's the first glimpse of how you can change some content here in that folder structure.

A

Just upload something in here and you can see, we have now an open api file in place.

A

So with those basic changes where we are simply changing, pre-configured things,, let's now.

A

Really get under the hood and have a look and how we can really customize things in.

A

A little bit more detail., the first thing you want to change is looking here at the homepage is we do have this welcome.

A

Message "built with kong", and you want to change that to something different.

A

So how do we do that once again? well, we're having a look first here on our editor again,, and this time we are talking.

A

About a content., you see here all the files and the content section which are available here on the pages.

A

Towards the login page,, where you can login to the dev portal,, there's a register page.

A

Where you can register and there's also the index page, that's in fact the homepage page.

A

We are just looking at. and notice. We also have this live preview everywhere in here.

A

First thing,: we want to change the text., so let's say this is our dev portal.

A

And the tagline we want to have "cool." save changes.

A

Already live in a preview., and here and now we have our dev patel and cool being customized.

A

So far so good., how does that look? Like?, well,? We can see it's a yaml file.

A

The yaml file has a section called "hero" and we do have a title and a tagline.

A

But how does kong know how to render that file that it should look like it does on the.

A

Right hand: side? that's described here on the top., it's saying it's using the layout called homepage.

A

And now we come to the very central concept of kong.

A

Every content is a yaml file like we see here..

A

Every content is a yaml five, which describes something like hero title or hero tagline.

A

And each of those yaml files is rendered by a template.

A

In this case, homepage.htlm., so let's have a look and look for this homepage.html.

A

We already have the themes: folder open.

A

We do have layouts.

A

and under layouts we do have,, we can see it: homepage.html.

A

So we see here, ok,, there are some html in place and some other things being included.

A

What's that? we can see, it looks like that homepage consists of sub templates.

A

That's the hero., that's that part.! Then we have the catalog here.

A

And then we have just a small clients list,, which is quite empty right now, down here.

A

So we're looking now for this hero, part,, which is the above part.,.

A

And if we can find here in the partials as written, here,, partials homepage hero.

A

And here you can see everything can be customized,, so we can create here any html,. Any javascript,.

A

Any css,, whatever you want to do in here, can be done by you here in any kind.

A

So let's say we want that one also be in an h2,. So that's a "cool" tagline should be as.

A

Big as the title., so I see hero.title, hereo.tagline, those have been the yaml fields. We have seen before,.

A

And now just saying that the second one,, the tagline, should be the same size.

A

And now that's also called "cool.", but we can go beyond that.. We can change everything in here..

A

So let's get back to our actual content where we have title and tagline defined.

A

Let me go back to our index and just say: "dev" and "this is our text.".

A

This is the yaml structure and that can be fully creative on doing anything with that.

A

Yaml file,, I can create my own structure with arrays in it,, whatever I want to do.

A

You have a full yaml file, so you can be as creative as you want.

A

As you have just seen,, I've changed now that file,, but nothing has changed.

A

Why is it the case?? Because we have never told the developer portal? How to render that--we just have said? There's.

A

A new field called "dev" here. that "dev" is not available,, but not rendered..

A

So you can go back to our hero template..

A

I can just say we want to have that one being read once again as a paragraph.

A

As I said, it could be any css in here,. You can make it red,, blinking or whatever you.

A

Want. and we want to have here,, not the tagline,, we want to have the "dev" part in place. Here.

A

So save changes., and now this is our text: hero.dev,, which is exactly what we have specified. Here: hero.dev.

A

This is our text. and you might get already a first feeling. yeah,. You can create your own structures,, your own template,, whatever you want to do.

A

In here. you're not limited to use the ones already being baked in., you can create your own partials and layouts as many as you want to change anything here.

A

On the homepage, so that in the end, you can define from scratch your own design. However,.

A

It looks like. if you want to have the navigation somewhere else,. If you want to have everything with.

A

Html,, if you want to have the typical content screen,, whatever you want to have,, you have.

A

Full control on whole html using that technology stack.

A

So how about an example on to change something which is not only a very simple structure.

A

Like an html?, so let's do an example with css.

A

So, as you might have noticed on the appearance section,, we do have branding for the logo.

A

And the favicon,, but let's say we want to change something completely different.

A

We want to go down here and change that background. Image.

A

Well,, how do we do that? Again?.

A

In fact,, that's driven by a css.

A

So we can once again go in our editor,. Look at our theme, look at the assets part and.

A

Then you can see, by the way,, you can upload your other images and you can upload other.

A

Javascript fully open to do so., we do have a style section. and let's say we want to add something here to that layout where, by the way,. Everything.

A

Which you have seen so far has been applied in here.

A

So we want to change something here. and I already have got a new image..

A

I got it from my marketing department and they say the background image should look.

A

Like this one. yeah,, we now have here our connectivity company logo in place.

A

So we are taking that one, and we want to put it here in that container.

A

And if you know about css and html,, you just need to know how the class of that container.

A

Is that's called homepage.hero., so what we will do now, and I'm having that ready to not mistype something in place.

A

We're saying for homepage.hero,: we want the background image to the image we just specified.

A

Saving the changes.

A

Going back to our dev portal, reloading in here and now we can see we have now our dev.

A

Portal being customized in here.

A

So that's the first thing where we can see we are changing here, the layout more than.

A

What is pre built into the system.?

A

We have made some crazy stuff on our dev portal.

A

It does not really look nice in here.

A

And remember, we can always change the colors..

A

We can still go back to our appearance section and say you want to change the hero. Color.

A

Hero,, hero text color to be more specific., that is right now white and once again we want to make it our dark blue. So it's readable.

A

Again. so nicely placed together, our hand-crafted stuff, plus the one which can be clicked.

A

Reloading in here and now our dev portal text is readable again and everything is still.

A

Being accessible down here.- and this is just a basic example.- you can skin everything you can put in your own javascript everywhere.

A

That's how it works, that you can change the whole layout.

A

You can make non-round buttons..

A

You can make a nice hover effect., whatever you want., you have full control about html and css.

A

So let's get to the next level., so far, we have just used our existing templates.

A

How do we create our own template in the end?.

A

So how can you create our own structure and our own template to be rendered in our dev.

A

Portal?, let's say we want to have a news section as part of our dev portal.

A

So what can we do?? We can go back to our editor.

A

ok,. Just say we want to have a new file in our content, section,, which we want to call.

A

News.Yaml, for example.

A

and we're getting here a skeleton of an entry.

A

Let's call that one "news." underneath news,, we have a title,, our headline,, then we have text,. We say "this is the news.

A

Entry with everything in there.".

A

Let's call it also news upper case.

A

So far, we're not doing anything., as we have seen with our examples. Before, we can now choose our layout.

A

And also here you can be creative., you can just say: "we want to use the layout called news.html.

A

A

huh?, nothing has happened.

A

well,. We do not have a news.html layout.

A

So go down to "base" and see "layout"...nothing about news,, but we can create it.

A

We can just say new file in our theme folder, and we want to save it in our base/layouts/news.html.

A

That's how we just called it in our content, file.

A

Oh, right now already rendering something, we already have something pre-baked.

A

We want to use something from our yaml, so we can use your curly brackets and say from.

A

The page,, the news,, the title.

A

Our headline., why is it page,, news, title?.

A

Well, have a look at our news, and that's our page,. That's the news.title, and we also.

A

Have .text. so you can go down to our news again and say, "let's make a small line, and then we say.

A

As a paragraph,, we want to have once again page.news.text.

A

And also as a paragraph.

A

Ok. now,, we already have done most of the work.

A

We have now created a news. Entry.

A

in here was the headline., and now you can imagine with the date, with images,, whatever you would prefer to put in.

A

Place for a news entry., but the one thing we are missing is right. Now that is just white..

A

Does it even render?, so we can go ahead to our dev portal and just have a look at /news.

A

But there's no navigation.: now we can simply have a small look, how we can include the other templates.

A

That's what we have seen already with the hero in the beginning.

A

And we just will borrow something from another template..

A

We will just go to about page., we can just see,. Ok, we do have a general page layout and we have to surround the content.

A

Itself by the content, section.

A

ok, use, where we are just saying we want to have that one also being rendered with in.

A

Our full layout.- and this is then the actual content in that layout.

A

And boom here we are also here on the big page.

A

We can see now,, we are getting once again our navigation back,, we're getting here. Our.

A

Headline and so on, and our footer is also back in place.

A

Now, up to your creativity to create your own structure.

A

Whatever it is,, you can build it here in this very easiest way of defining contents and.

A

Templates, according to them.

A

There's now one more thing which we also want to have here.

A

Well,, I just knew that url.

A

yeah. now,. If I do not know, there's news,, how can I do that?.

A

Well, you already have seen there are some navigation up here, and we already saw on.

A

A glimpse of in that file there is a navigation up, here.

A

So let's say we want to have that news in here in the menu,. You can just say we want.

A

To have another menu entry next to the catalog,, which is called "news.".

A

It should point to "news,", which is in fact here this file name.

A

I could also make log out, log in and so on.

A

and here,, I just say to news, and we say that's a public page.

A

You can also make it here log in only or roles-based,, but we just say it's a public page.

A

So we go ahead, reload.. Now we have a news entry and we have our headline here in place.

A

So that quickly we can extend the content, the structure of the content,, as well as the.

A

Main navigation to show it..

A

Let's say we have done all those things,, but we are living in a ci/cd world and devops.

A

World, and so far we did everything using the browser as an interface.

A

But we want to automate such changes like changing files and uploading things.

A

And here we come back to a very core principle of kong,, which is everything in kong. Is an.

A

Api,- and this is also true for the whole developer, portal.

A

Let me show you what I mean.

A

yeah,: that's our developer portal, as we have just worked with the whole day, so far.

A

Let's look, have a look at the administration api running here on 8001.

A

You might know notice you can remote control your installation, completely.

A

And there's one endpoint called files.

A

On files, I'm getting the whole developer portal, and by whole, I really mean everything.

A

Everything which we have seen here in our editor.

A

All those files, all contents,, all specs,, all themes.

A

Everything is here on that endpoint., so we just created and one for the news,. So we can just say that for something we put.

A

Into the content, folder: content/news.yaml.

A

And we can see here's our news file with our title, news, layout and an our headline and.

A

So on.- and this is a full api, so we can create those files update those files, delete those files,.

A

So you can automate everything,, you can upload images,, you can upload yaml files, templates,.

A

Everything can be uploaded and changed using that api, just as example.

A

Yeah., we already have here in our system some specifications, as they already have uploaded here in the.

A

Catalog,, our random facts, one,, and we also have here swagger pet store and shipping from.

A

The beginning. and we can use that api to upload something else..

A

I do have some examples here in place..

A

Let's say we also want to have a movies.

A

Specification in place. we can use the admin api, /files and say,. We want to upload it,. We want to upload it to.

A

The specs folder.- that's in fact the folder, where our specifications are located.

A

in our system,. We want to call it movies.json.

A

And then the contents, we also want to get from that file.

A

A

automated the publishing to the dev portal., going back to our catalog, and here's our movies api.

A

So everything can be uploaded, changed,. You can upload the navigation, the css, everything.

A

Is in that api and can be part of a ci/cd pipeline.

A

We have changes using the api,, but is there another way to create such files in an,? I.

A

Would say, more convenient way for the web developers?

A

and the answer is obviously yes.

A

And you see on our github, there's a kong portal cli.

A

That's a tool,, which I already have installed,, where you can remote control your portal using.

A

A cli. to do so, as described down here,. You want to have first, the portal templates repo being.

A

Cloned to your machine.

A

So I'm going ahead. and saying I'm going to make the video and say git clone boom.

A

What we get here is now we are getting from the repo,, the standard layout,, the one which.

A

We have started earlier today with the standard, graphics and so on.

A

So they are all in here.. So if I go here and make an ls workspaces/default/content,, you see there's a portal kong file,. There.

A

Is the the contents like the index page,, but still the one which has been there from the.

A

Beginning., so if I look at that, content/index page,, that's the standard one as it comes out of the box.

A

That's in fact the one being applied when you just create a new developer, portal.

A

Now we can work with the portal cli..

A

I said I already had it installed on my machine.

A

Now it tells me what I can do.. What can I do?, where I can say: "I want to use portal to fetch an existing dev portal and that's the one.

A

From my default workspace.", why is it the case? well,? We all have been all the time working here.

A

in fact, in the default workspace,, so it can fetch different workspaces, different portals.

A

So we say fetch that one.

A

And now let's have a look at the same file again. and we will notice, oh,. They are our changes. and now,. We can do things. two things.. First of all, we can use the editor of choice.

A

Yeah,, the first thing, visual studio code or whatever your developers, might prefer to create.

A

In here., we can go ahead and see here all the contents,, all the about page.

A

What else do we do??

A

We did also in the content part,, we did the news, yaml file.

A

There's a news.yaml file. or we did change the templates, themes, layouts. There's our news. Template.

A

And we can change everything in here., but first,. Let me do something else.

A

I will say portal deploy, so I can deploy back to kong. What I'm changing here in my local.

A

Dist. mine is watch. and once again, the default one.

A

So, let's see,, we do have here our dev portal on the homepage and we're now wiping it.

A

And now we want to change the text on the homepage once again.

A

That now deployed. sorry, wrong: it's not deployed.! So once again, we have our dev portal,. This is our text., and now we go ahead and say, well on the homepage,. It was in the folder of content,. It was the.

A

Index page, our dev portal tagline "cool," "this, is our text,", and now we say, "this.

A

Is my editor." I'm saving it here, command s.

A

And already,, if I reload it here.

A

You can see it's updated..

A

Why is that the case? when I said portal deploy, I also had this -w,, which means I'm watching everything. I'm.

A

Doing locally, so everything I change here will immediately be uploaded.

A

So the moment I saved the index file, like I did in here, it got uploaded to my dev portal.

A

So for a developer,, a very nice way to create his own designs with his most beloved editor,.

A

With the most beloved frameworks around him,, he can just work on his local machine and.

A

Then directly have a live updating system up and running in here.

A

So that's what we have for you today., that's about customization for the dev portal, from the very basics, to quite some detail.

A

Like here in the end., see you again, soon.