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.

About the sample React app

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 custom resource 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 custom resource, you don’t have to update the frontend app as often after the initial setup.

For more information and the source code, review the dev-portal-starter GitHub project.

Customize the frontend app for your brand

You can customize the sample React app to reflect your brand’s logos, colors, icons, and other branding elements. For more information, review the dev-portal-starter GitHub project’s Readme.

  1. Clone the sample React UI app’s GitHub project.
      git clone https://github.com/solo-io/dev-portal-starter.git
  2. 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
  3. Replace the sample images for the banner and cards in projects/ui/src/Assets/ with your own images.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. Build and deploy (or re-build and re-deploy) the frontend app.

Build your frontend app

After customizing the sample React app, you can build an image to deploy to your cluster. 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.

  1. Build and push a Docker image to your container registry. Choose from among the following options.

    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

After customizing the sample React app and building an image, you deploy the app to your cluster.

The following tutorials have steps for deploying the app. Update the Kubernetes deployment in the steps to refer to your custom image.

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.

When you are ready, share the developer portal guide with your end users so that they know how to interact with the developer portal.