Navigation :

Gloo Portal frontend app

Develop a frontend user interface (UI) application for your Gloo Portal custom resource (CR) so that your end users can explore, authenticate, and use your API products.

Your end-users need a way to find, review, and use your API products. As such, you must be able to customize the developer portal's frontend app so that your company style, logos, and other branding elements are consistent.

Gloo provides a sample React app that you can use as a starting point to develop your frontend application. This frontend app displays the information that your Portal CR pulls together: the API products and usage plans that you want to expose, along with additional metadata. Because this information is controlled by the Portal CR, you don't have to update the frontend app as often after the initial setup.

Before you begin

Configure the developer portal, including to create and expose the portal server securely.
Make sure that you set up the OAuth external authentication policy for the OIDC provider that you want to use, such as Keycloak or Okta.
Configure the OAuth details to protect your frontend app. The steps vary by OIDC provider.
- Okta
- Keycloak
Follow the Okta access token example to configure Okta and create the external auth policy.
1. Follow the steps to install Keycloak.
2. Follow the steps to configure Keycloak.
3. Create the secret and ext auth server. Note that you can skip creating the httpbin sample app route table, as you create a route table for portal later.
4. Configure OAuth with external auth policy for access token validation.

Build your frontend app

To help you build a frontend app, Gloo Gateway provides a dev-portal-starter sample React GitHub project. The following steps show you how to containerize the application locally by using Docker. You might also build and push the Docker image to a container registry, such as DockerHub or your cloud provider's registry.

Build and push a Docker image to your container registry. Choose from among the following options.
You can use a sample container image in Solo's public image registry, gcr.io/solo-public/docs/portal-frontend. Continue to the next step.
Build and push the container image to your own container image registry, <image-registry>. For most production use cases, you use a private container image registry, such as offered by your cloud provider. Keep in mind that when you deploy the app, your cluster must have access to this private container image registry.
1. Clone the sample React UI app's GitHub project.
  git clone https://github.com/solo-io/dev-portal-starter.git
2. Optional: Customize the frontend app for your brand before you build and push the image.
3. Follow the Readme instructions to build a local Docker container image. Make sure to replace IMAGE_NAME with the container image registry that you want to use.
4. Push the Docker container image to your container image registry.
  docker push $IMAGE_NAME/portal-frontend:latest
If you make changes to the app, you might want to test these before pushing to your private container registry. You can build and push the image to the local Docker container image registry. Keep in mind that when you deploy the app, your local environment must have access to this local Docker registry, such as in a Kind cluster.
1. Clone the sample React UI app's GitHub project.
  git clone https://github.com/solo-io/dev-portal-starter.git
2. Optional: Customize the frontend app for your brand before you build and push the image.
3. Run the local Docker container image registry.
```
docker run -d -p 5000:5000 --restart always --name registry registry:2
```
4. Follow the Readme instructions to build a local Docker container image. Replace IMAGE_NAME with the local Docker registry, localhost:5000.
5. Push the Docker container image to the local Docker registry.
  docker push localhost:5000/portal-frontend:latest
Deploy the frontend app.

Deploy the frontend app

After containerizing your app, you can deploy the app to the same cluster that runs your developer portal.

Create a secret with the details of the OAuth identity provider that you use for external authentication to your Gloo Platform Portal. Replace the variables with the values that you previously retrieved. For more information, see the OAuth step in Before you begin.
- VITE_PORTAL_SERVER_URL: The URL that the Gloo Platform Portal REST server is available on. This URL matches the host in the route table for the gloo-mesh-portal-server, such as http://developer.example.com. You can check the hostnames of your route tables with the following command. For local development, use the default value http://localhost:31080/v1. Format this variable with a /v1 path, such as: http://developer.example.com/v1.
- VITE_CLIENT_ID: The OAuth identity provider's Client ID.
  - In Keycloak, open the $KEYCLOAK_URL, click Clients, and from the Settings tab, find the Client ID.
  - In Okta, open the $OKTA_URL and from the Applications section, find your app's Client ID.
- In your OAuth provider, access the well-known OpenID config path for your authorization server, such as the following examples for Keycloak and Okta.
  - Keycloak OpenID config path: $KEYCLOAK_URL/auth/realms/<your-realm>/.well-known/openid-configuration
  - Okta OpenID config path: $OKTA_URL/oauth2/default/.well-known/openid-configuration
- From the OpenID config path, get the values for the following endpoints:
  - VITE_TOKEN_ENDPOINT: The endpoint to get the OAuth token.
  - VITE_AUTH_ENDPOINT: The endpoint to get the PKCE authorization code.
  - VITE_LOGOUT_ENDPOINT: The endpoint to end the session.
Keep in mind that the Portal URL and OAuth endpoints that you set in the deployment configuration must match. For example, if you use a secure HTTPS gateway, then the Portal URL and OAuth endpoints should begin with https:// instead of http://.
```
kubectl apply -f- <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: portal-oauth-secrets
  namespace: gloo-mesh-addons
type: Opaque
stringData:
  VITE_PORTAL_SERVER_URL: "http://developer.example.com/v1"
  VITE_CLIENT_ID: "$CLIENT_ID"
  VITE_TOKEN_ENDPOINT: "$TOKEN_ENDPOINT"
  VITE_AUTH_ENDPOINT: "$AUTH_ENDPOINT"
  VITE_LOGOUT_ENDPOINT: "$LOGOUT_ENDPOINT"
EOF
```
Create the Kubernetes resources that you need to run your portal frontend app.
- ServiceAccount: Create a separate service account for your frontend app so that its identity is separate from the other apps that run in the namespace.
- Service: Create a service for the frontend app so that you can expose it securely.
- Deployment: Create a deployment to run the frontend app.
  The following example uses a sample image from Solo's public image registry. If you built your container image in a different container registry, copy and update the YAML configuration file image location before applying the file to your cluster.
```
kubectl apply -n gloo-mesh-addons -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-gateway/portal/frontend-deployment.yaml
```

Expose the frontend app securely through the ingress gateway. The following example uses the host developer.example.com. It refers to the virtual gateway that you created when you configured the developer portal. For more examples such as HTTPS/TLS, see Configure gateway listeners.

kubectl apply -f- <<EOF
apiVersion: networking.gloo.solo.io/v2
kind: RouteTable
metadata:
  name: portal-frontend
  namespace: gloo-mesh-gateways
  labels:
    app: portal-frontend
spec:
  hosts:
    - "developer.example.com"
  virtualGateways:
    - name: istio-ingressgateway-portal
      namespace: gloo-mesh-gateways
  http:
    - name: portal-frontend
      forwardTo:
        destinations:
          - port:
              number: 4000
            ref:
              name: portal-frontend
              namespace: gloo-mesh-addons
              cluster: $CLUSTER_NAME
      labels:
        route: portal-api
      matchers:
        - uri:
            prefix: /
EOF

Verify your frontend app.

Verify your frontend app

Now that you built and deployed your frontend app, you can access the developer portal in your browser.

Check that the frontend app's resources are healthy.

kubectl get all -n gloo-mesh-addons -l app=portal-frontend

Verify that you can access the developer portal frontend in your web browser. If you used the example in this guide, enter http://developer.example.com/ in your web browser.

If you click Login but see an Access issues error message or cannot view the APIs or usage plans, see Debug the frontend app for portal.

Next steps

Great job! You deployed the frontend app for the developer portal. Now, when you update your Portal resource to add new API products, usage plans, or metadata, the frontend is automatically updated for you.

If you didn't already, you can customize the frontend app for your brand.
Share the developer portal guide with your end users so that they know how to interact with the developer portal.

Customize the frontend app for your brand

You can customize your frontend app to reflect your brand's logos, colors, icons, and other branding elements. For more information, review the project's Readme.

Clone the sample React UI app's GitHub project.

git clone https://github.com/solo-io/dev-portal-starter.git

Replace the logo and favicon with your company's branding assets.
1. Replace the logo.svg file in projects/ui/src/Assets/logo.svg.
2. Replace the favicon in projects/ui/public/favicon.svg
Replace the sample images for the banner and cards in projects/ui/src/Assets/ with your own images.
Optional: Replace the fonts (projects/ui/src/Assets/fonts) and icons (projects/ui/src/Assets/Icons) with your company's preferred assets. You might want to keep the icons, however, and just change the color in the next step.
Change the color scheme in project/ui/src/Styles/_constants.scss to match your company's colors. In that file, you can also change the default icon colors.
Confirm the tool that you want to use to render your API docs.
- Default - Redocly: By default, Redocly is set up to render your API docs. Redocly provides an easy-to-use, three-part layout to your API docs. For an interactive demo, see ReDoc Pet Store.
- Swagger: Another popular editor is Swagger. With Swagger, you can also provide a Try it out button for users (Redocly requires a paid plan for this functionality). For an interactive demo, see Swagger Editor. To switch to use Swagger, comment out the Redocly and uncomment the Swagger section in the projects/ui/src/Components/ApiDetails/ApiSchemaDisplay.txs file as follows.
```
/** Redoc - Default */
/* Comment out the Redoc line
return <RedocDisplay spec={apiSchema} />;
*/

/** Uncomment the Swagger lines
 * Swagger - Alternative
 */
return (
  <SwaggerDisplay
    spec={apiSchema}
    apiId={apiId ?? "Unsupported schema display"}
  />
);
```
- Use another editor: In the projects/ui/src/Components/ApiDetails/ directory, create a sibling file to the RedocDisplay.tsx and SwaggerDisplay.tsx files. Then, update the projects/ui/src/Components/ApiDetails/ApiSchemaDisplay.tsx file similar to the previous step.
Optional: For more changes, you can edit any of the app files. Review the comments throughout the code and your company's own frontend styling guidelines.
Build and deploy (or re-build and re-deploy) the frontend app.