Set Up a Developer Portal

Learn how to use NGINX Management Suite API Connectivity Manager to configure a Developer Portal.

Overview

In NGINX Management Suite API Connectivity Manager (ACM), a Developer Portal (or, “Dev Portal”) is a cluster of NGINX Plus data plane instances. These clusters are managed under Infrastructure Workspaces and are part of Environments.

Before You Begin

You should complete the following Quick Start Guide(s) before proceeding with the steps in this guide:

Add a Developer Portal Cluster

Complete the steps in this guide to add a Developer Portal Cluster to the Environment you created in the previous guide.

When you deploy a Dev Portal Cluster, ACM also creates an Internal Dev Portal Cluster. NGINX Management Suite uses this cluster to send internal communications between ACM and the Dev Portal.

Important:
  • Be sure to provide the IP address or FQDN of the host where you installed the Dev Portal packages as the {{portalClusterHostname}}.
  • The Dev Portal must run on a dedicated host with the njs module installed.

Use the appropriate example below to deploy an HTTP or HTTPS Dev Portal Cluster.

HTTP

Use this example to get up and running quickly in a demo environment.

Method Endpoint
POST /infrastructure/workspaces/{{infraWorkspaceName}}/environments

{
    "name": "{{environmentName}}",
    "functions": [
        "DEVPORTAL"
    ],
    "proxies": [
        {
            "proxyClusterName": "{{portalInstanceGroupName}}",
            "hostnames": [
                "{{portalClusterHostname}}"
            ],
            "runtime": "PORTAL-PROXY"
        }
    ]
}

HTTPS

To deploy a cluster that uses HTTPS for secure inbound communication, you’ll add the TLS Inbound policy. Because this is done at the Infrastructure level, this is considered a “Global Policy”.

You need to provide your TLS server certificate and key as base64-encoded strings in this API call.

Method Endpoint
POST /infrastructure/workspaces/{{infraWorkspaceName}}/environments

{
    "name": "{{environmentName}}",
    "functions": [
        "DEVPORTAL"
    ],
    "proxies": [
        {
            "proxyClusterName": "{{portalInstanceGroupName}}",
            "hostnames": [
                "{{portalClusterHostname}}"
            ],
            "runtime": "PORTAL-PROXY",
            "policies": {
                "tls-inbound": [
                    {
                        "data": {
                            "serverCerts": [
                                {
                                    "key": {{tls key}},
                                    "cert": {{tls cert}}
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

Onboard an NGINX Plus Instance into the Cluster

Take the steps in this section to install the NGINX Agent on the data plane instance where you installed the Developer Portal packages. This onboards the host into the proxy cluster that you created in the previous step.

To do so, you’ll need to interact directly with the host. SSH access to the host and sudo permissions are required.

Install NGINX Agent on the Data Plane Host

See Also:
Refer to the NGINX Agent Install Guide for more information.
  1. Use SSH to connect and log in to the Dev Portal host.

  2. Run the onboarding command as root to download, install, configure, and start the NGINX Agent package.

    • Replace {{nms-fqdn}} in the example command with the FQDN or IP address of your Dev Portal host.
    • Replace {{clusterName}} in the example command with the name of your Dev Portal cluster.
    curl -k https://{{nms-fqdn}}/install/nginx-agent > install.sh && \
    sudo sh install.sh -g {{clusterName}} && sudo systemctl start nginx-agent
    

Update the DNS Record

The F5 NGINX Management Suite management plane host uses the Dev Portal Cluster’s hostname to communicate with the Dev Portal. You’ll need to update your DNS resolver settings with the Dev Portal Cluster’s internal hostname.

The internal hostname is the hostname that you provided for the Dev Portal cluster, prefixed with acm.. For example: acm.dev-portal.io

Next, open the Developer Portal in a browser window and make sure the portal loads.

Customize the Developer Portal

In this step, you’ll apply a set of customizations to the Developer Portal. Because these settings are applied at the Infrastructure level, they are considered “global”, meaning they apply to each Dev Portal Proxy that you associate with the cluster.

See Also:
Refer to Customize the Developer Portal to learn more about the available customization options and how to customize a Dev Portal via the ACM user interface.

Method Endpoint
PUT /infrastructure/workspaces/{{infraWorkspaceName}}/devportals/{{devPortalName}}

Note that many fields in the example JSON payload – including the logo image and Markdown documents – are base64-encoded.

Example JSON payload: customize-devportal.json

Before you move on to the next guide, open the Dev Portal in your browser to view the changes. You should see the default Dev Portal replaced by the custom settings.