Create a Portal UI

Once a set of APIs have been bundled together in an API Product, those products can be published in a user-friendly interface through which developers can discover, browse, request access to, and interact with APIs. This is done by defining Portals, a custom resource which tells the Dev Portal how to publish a customized website containing an interactive catalog of those products.

In this guide we are going to create a Portal UI using the Admin Dashboard.

Pre-requisites

You will need to have the Dev Portal deployed on a Kubernetes cluster, and a connection to the Admin Dashboard as described in the Using the Admin Dashboard guide. You will also need an API Doc created through the Create an API Doc guide and an API Product created through the Create an API Product guide.

Finally, you will need an instance of the Petstore application deployed on Kubernetes. If you don’t already have an instance created, go ahead and run the following command:

kubectl apply -n default -f \
  https://raw.githubusercontent.com/solo-io/gloo/v1.3.7/example/petstore/petstore.yaml
kubectl -n default rollout status deployment petstore

Create a Portal UI

We will start from the Overview page of the Dev Portal. First you will click on the Portals item in the navigation bar to manage Portals,API Products, and Access Control.

Admin Dashboard Nav Bar

The page should load on the Portals category by default. Next click on the Create a Portal button to start the process.

Admin Dashboard Create API

On the General page, you will fill out the basic fields for the Portal.

Admin Dashboard Create Portal General

In our example we are going to use the following values:

The portal domain defines the domain name where the portal will be accessible.

Then click on Next Step to move to the Imagery page. The imagery page allows you to add a graphic for the banner of the website.

Admin Dashboard Create Portal Imagery

We are going to add an image from a URL. To do so, click on Upload an Image and paste in the value: https://i.imgur.com/EXbBN1a.jpg then click on OK in the file dialog box. The downloaded image will appear on the screen.

Admin Dashboard Create Portal Upload

Then click on Next Step to move to the Branding page. On this page you can set the primary logo and favicon for the Portal UI site.

Admin Dashboard Create Portal Branding

Following the same process as the imagery page, use the following values:

The downloaded images will appear on the screen.

Admin Dashboard Create Portal Upload Brand

Then click on Next Step to move to the APIs page. This page allows you to select which API Product to make available through the portal.

Admin Dashboard Create Portal APIs

From the Available APIs list select the Petstore Product v2 item and click on the green plus sign to add it to the Selected APIs list.

Admin Dashboard Create Portal APIs Selected

Then click on Next Step to move to the User Access page.

Admin Dashboard Create Portal Users

At this point we do not have any users to add, so simply click on the Next Step button to move to the Group Access page.

Admin Dashboard Create Portal Groups

We also do not have any groups to add, so click the Create Portal button to complete the process.

The portal should now show as available from within the Admin Dashboard.

Admin Dashboard Create Portal Complete

The next step is to connect to the Petstore Portal in a browser.

Connect to the Portal UI

Now that the Portal has been created, we are going to connect to it using the browser.

Setting up DNS for the Browser

In order to visit the Portal being served at our domain petstore.example.com, we’ll need to make sure a DNS rule exists that will resolve that domain to that address.

There are many ways to set up DNS rules for the domains defined in our API Products and Portals. In production environments, you will probably want to use your Cloud Provider’s DNS solution.

For the purposes of this setup, modifying your local /etc/hosts file with an entry to manually resolve the API Product and Portal domains will be sufficient.

Let’s add entries for the api.example.com and petstore.example.com domains. Make sure you’ve got the INGRESS_HOST and INGRESS_PORT environment variables set before running:

cat <<EOF | sudo tee -a /etc/hosts

# Added for the Dev Portal Guides
${INGRESS_HOST} api.example.com
${INGRESS_HOST} petstore.example.com
EOF

Verify the Portal UI

Now that DNS is set up for our domains, we should be able to access the portal directly in the browser at http://petstore.example.com:${INGRESS_PORT}. Try typing this address into your browser with the correct INGRESS_PORT:

open $(echo http://petstore.example.com:${INGRESS_PORT})

Once the browser opens you should see a page that looks something like this.

Portal UI

If we click on the APIs area, we will find that there are no APIs to display.

Portal APIs

In order to access and use the Portal UI, you will need to create users and groups for the site.

Using kubectl

If you wanted to create the same Portal UI using kubectl you could do so with the following two commands.

The first command creates the Portal Custom Resource:

cat <<EOF | kubectl apply -f -
apiVersion: devportal.solo.io/v1alpha1
kind: Portal
metadata:
  name: petstore-portal
  namespace: dev-portal
spec:
  displayName: Petstore Portal
  description: Petstore Portal
  banner:
    fetchUrl: https://i.imgur.com/EXbBN1a.jpg 
  favicon:
    fetchUrl: https://i.imgur.com/QQwlQG3.png
  primaryLogo:
    fetchUrl: https://i.imgur.com/hjgPMNP.png
  customStyling: {}
  staticPages: []
  domains:
  - petstore.example.com
  publishApiProducts:
    matchLabels:
      portals.devportal.solo.io/dev-portal.petstore-portal: "true"
EOF

The second command applies a label to the Petstore Product v2 Custom Resource to associate it with the Portal.

kubectl label apiproduct -n dev-portal petstore-product-v2 portals.devportal.solo.io/dev-portal.petstore-portal="true"

Next steps

The Portal UI isn’t much use without users and groups. You can follow our guide for creating users and groups through kubectl or through the Admin Dashboard.