Install the new Edge UI

This document describes how to install the Edge UI for Apigee Edge for Private Cloud. The Edge UI is the next generation of UI for Edge.

Prerequisites

To try out the new Edge UI in an Apigee Edge for Private Cloud installation, you must:

Install the Edge UI on its own node. You cannot install it on a node that contains other Edge components, including the node on which the existing Classic UI resides. Doing so will cause users to be unable to log in to the Classic UI.
The Edge UI's node must meet the following requirements:
- JAVA 1.8
- 4 GBytes of RAM
- 2-core
- 60GB disk space
- You must first install the 4.53.00 version of the apigee-setup utility on the node as described at Install the Edge apigee-setup utility.
- Port 3001 must be open. This is the default port used for requests to the Edge UI. If you change the port by using the properties described in New UE configuration file, make sure that port is open.
Enable an external IDP on Edge. The Edge UI supports SAML or LDAP as the authentication mechanism.
(SAML IDP only) The Edge UIonly supports TLS v1.2. Because you connect to the SAML IDP over TLS, if you use SAML, your IDP must therefore support TLS v1.2.

For more on the Edge UI, see The new Edge UI for Private Cloud.

Installation overview

At a high level, the process for installing the Edge UI for Apigee Edge for Private Cloud is as follows:

Add a new node to your cluster
Log in to the new node
Download the apigee-setup utility
Create a configuration file and modify it with your settings
Execute the apigee-setup utility
Log in and test to new UE

When executed on the new node, the apigee-setup utility:

Installs the base Classic UI, called shoehorn, and configures the Classic UI to use an external IDP to authenticate with Edge.
NOTE: You cannot use the installed Classic UI to connect to Edge. It is simply a requirement for installing the new Edge UI.
Installs the new Edge UI, and configures the Edge UI to use your external IDP to authenticate with Edge.

Considerations before installing the new Edge UI

As described above in the prerequisites, the Edge UI requires that you enable an external IDP on Edge. That means user authentication is controlled by the IDP, where you configure it to use email addresses as the user ID. All Edge UI users must therefore be registered in the IDP.

The Classic UI, the default UI you installed with Apigee Edge for Private Cloud, does not require an external IDP. It can use either an IDP or Basic authentication. That means you can either:

Enable external IDP support on Edge and on both the Classic UI and the Edge UI.
In this scenario, all Classic UI and Edge UI users are registered in the IDP. For information on adding new users to the IDP, see Register new Edge users.
Enable external IDP support on Edge, but leave Basic authentication enabled. The Edge UI uses the IDP and the Classic UI still uses Basic authentication.
In this scenario, all Classic UI users log in with Basic authentication credentials, where their credentials are stored in the Edge OpenLDAP database. Edge UI users are registered in the IDP and log in by using either SAML or LDAP.

However, a Classic UI user cannot log in to the Edge UI until you have added that user to the IDP as described in Register new Edge users.

Installation configuration changes from previous releases

Be aware of the following changes to the installation procedure from the Beta releases of the Edge UI.

Installation configuration changes from Edge 4.18.05

The Edge 4.53.00 release of the Edge UI contains the following changes to the configuration file from the Edge 4.18.05 release:

Change type	Affected properties
Removed	MANAGEMENT_UI_SSO_PUBLIC_KEY_CACHE_HOURS That property has a predefined value of 0.5 (30 minutes) and cannot be changed.
Added	You can now use properties to enable TLS on the Edge UI. See Configuring TLS for the Edge UI for more.

Installation configuration changes from Edge 4.18.01

The Edge 4.53.00 release of the Edge UI contains the following changes to the configuration file from the Edge 4.18.01 release:

Change type	Affected properties
Added	# Shoehorn/Classic UI configurations. SHOEHORN_SCHEME SHOEHORN_IP SHOEHORN_PORT # Classic UI configurations. CLASSIC_UI_SCHEME CLASSIC_UI_IP CLASSIC_UI_PORT # Information about Edge SSO module. MANAGEMENT_UI_SKIP_VERIFY
Removed	ROUTES_SHOEHORN ROUTES_CLASSICUI
Replaced	MANAGEMENT_UI_USE_HTTPS Replaced by: MANAGEMENT_UI_SCHEME

Change type

Affected properties

Added

# Shoehorn/Classic UI configurations.
SHOEHORN_SCHEME
SHOEHORN_IP
SHOEHORN_PORT

# Classic UI configurations.
CLASSIC_UI_SCHEME
CLASSIC_UI_IP
CLASSIC_UI_PORT

# Information about Edge SSO module.
MANAGEMENT_UI_SKIP_VERIFY

Removed

ROUTES_SHOEHORN
ROUTES_CLASSICUI

Replaced

MANAGEMENT_UI_USE_HTTPS

Replaced by:

MANAGEMENT_UI_SCHEME

New Edge UI configuration file

The following configuration file contains all the information necessary to install and configure the new Edge UI. You can use the same configuration file to install and configure both the shoehorn/Classic UI and the Edge UI.

# IP of the Edge Management Server.
# This node also hosts the Apigee SSO module and the current, or Classic, UI.
IP1=management_server_IP

# IP of the Edge UI node.
IP2=edge_UI_server_IP

# Edge sys admin credentials.
ADMIN_EMAIL=your@email.com
APIGEE_ADMINPW=your_password    # If omitted, you are prompted for it.

# Edge Management Server information.
APIGEE_PORT_HTTP_MS=8080
MSIP=$IP1
MS_SCHEME=http

#
# Edge UI configuration.
#

# Enable the Edge UI.
EDGEUI_ENABLE_UNIFIED_UI=y
# Specify IP and port for the Edge UI.
# The management UI port must be open for requests to the Edge UI
MANAGEMENT_UI_PORT=3001
MANAGEMENT_UI_IP=$IP2
# Set to 'OPDK' to specify a Private Cloud deployment.
MANAGEMENT_UI_APP_ENV=OPDK
# Disable TLS on the Edge UI.
MANAGEMENT_UI_SCHEME=http

# Location of Edge UI.
MANAGEMENT_UI_PUBLIC_URIS=$MANAGEMENT_UI_SCHEME://$MANAGEMENT_UI_IP:$MANAGEMENT_UI_PORT
MANAGEMENT_UI_SSO_REGISTERED_PUBLIC_URIS=$MANAGEMENT_UI_PUBLIC_URIS
MANAGEMENT_UI_SSO_CSRF_SECRET=YOUR_CSRF_SECRET
# Duration of CSRF token.
MANAGEMENT_UI_SSO_CSRF_EXPIRATION_HOURS=24
# Defaults to 8760 hours, or 365 days.
MANAGEMENT_UI_SSO_STRICT_TRANSPORT_SECURITY_AGE_HOURS=8760

## SSO configuration for the Edge UI.
MANAGEMENT_UI_SSO_ENABLED=y

# Only required if MANAGEMENT_UI_SSO_ENABLED is 'y'
MANAGEMENT_UI_SSO_CLIENT_OVERWRITE=y

MANAGEMENT_UI_SSO_CLIENT_ID=newueclient
MANAGEMENT_UI_SSO_CLIENT_SECRET=your_client_sso_secret

#
# Shoehorn UI configuration
#
# Set to http even if you enable TLS on the Edge UI.
SHOEHORN_SCHEME=http
SHOEHORN_IP=$MANAGEMENT_UI_IP
SHOEHORN_PORT=9000

#
# Edge Classic UI configuration.
# Some settings are for the Classic UI, but are still required to configure the Edge UI.
#

# These settings assume that Classic UI is installed on the Management Server.
CLASSIC_UI_IP=$MSIP
CLASSIC_UI_PORT=9000
CLASSIC_UI_SCHEME=http
EDGEUI_PUBLIC_URIS=$CLASSIC_UI_SCHEME://$CLASSIC_UI_IP:$CLASSIC_UI_PORT

# Information about publicly accessible URL for Classic UI.
EDGEUI_SSO_REGISTERED_PUBLIC_URIS=$EDGEUI_PUBLIC_URIS

# Enable SSO
EDGEUI_SSO_ENABLED=y

# The name of the OAuth client used to connect to apigee-sso.
# The default client name is 'edgeui'.
# Apigee recommends that you use the same settings as you used
# when enabling your IDP on the Classic UI.
EDGEUI_SSO_CLIENT_NAME=edgeui
# Oauth client password using uppercase, lowercase, number, and special chars.
EDGEUI_SSO_CLIENT_SECRET=ssoClient123
# If set, existing EDGEUI client will deleted and new one will be created.
EDGEUI_SSO_CLIENT_OVERWRITE=y

# Apigee SSO Component configuration
# Externally accessible IP or DNS of Edge SSO module.
SSO_PUBLIC_URL_HOSTNAME=$IP1
SSO_PUBLIC_URL_PORT=9099
# Default is http. Set to https if you enabled TLS on the Apigee SSO module.
# If Apigee SSO uses a self-signed cert, you must also set MANAGEMENT_UI_SKIP_VERIFY to "y".
SSO_PUBLIC_URL_SCHEME=http
# MANAGEMENT_UI_SKIP_VERIFY=y
# SSO admin credentials as set when you installed Apigee SSO module.
SSO_ADMIN_NAME=ssoadmin
SSO_ADMIN_SECRET=your_sso_admin_secret

#
##      SSO Configuration (define external IDP)           #
#
# Use one of the following configuration blocks to        #
# define your IDP settings:                               #
#  - SAML configuration properties                        #
#  - LDAP Direct Binding configuration properties         #
#  - LDAP Indirect Binding configuration properties       #

INSERT_IDP_CONFIG_BLOCK_HERE (SAML, LDAP direct, or LDAP indirect)

## SMTP Configuration (required)
#
SKIP_SMTP=n       # Skip now and configure later by specifying "y".
SMTPHOST=smtp.gmail.com
SMTPUSER=your@email.com
SMTPPASSWORD=your_email_password
SMTPSSL=y
SMTPPORT=465      # If no SSL, use a different port, such as 25.
SMTPMAILFROM="My Company myco@company.com"

Install the Edge UI

After you create and modify the configuration file, you can install the new Edge UI on that new node.

To install the Edge UI:

Add a new node to your cluster.
Log in to the new node as an administrator.
Install the 4.53.00 version of the apigee-setup utility on the node, as described at Install the Edge apigee-setup utility.
Clean all cached information with Yum by executing the following command:
```
sudo yum clean all
```
Create the configuration file as described in New Edge UI configuration file and ensure that it is owned by the "apigee" user:
```
chown apigee:apigee configFile
```
Be sure that you make the following edits to the configuration file:
- Change the value of the MANAGEMENT_UI_SSO_CSRF_SECRET property in the configuration file to your CSRF secret.
  NOTE: Do not use the default value in the configuration file example above for your CSRF secret. Change it to a unique value that only you know.
- Configure Edge to use one of the following (the new Edge UI requires an external IDP):
  - SAML
  - LDAP
  For more information, see Overview of external IDPs authentication.
Configure your external IDP with the users that you want to have access to the Edge UI. For more information, see Register new Edge users.
On the new node, execute the following command:
```
/opt/apigee/apigee-setup/bin/setup.sh -p ue -f configFile
```
The apigee-setup utility installs the Classic UI. On top of the Classic UI, the installer then installs the Edge UI.
Log in to the Edge UI by opening the following URL in a browser:
```
http://new_edge_UI_IP:3001
```
Where new_edge_UI_IP is the IP address of the node hosting the new Edge UI.

Edge prompts you for your external IDP credentials.
Enter your credentials.
The new Edge UI appears. For information on using the Edge UI, see The new Edge UI for Private Cloud.

If the Edge UI does not display, then be sure that port 3001 is open for external connections.

Uninstall the new UI

To uninstall the new UI from its node, you must uninstall both the new Edge UI and the base Classic UI (shoehorn) that was installed on the node during the UI installation process.

To uninstall the new Edge UI:

/opt/apigee/apigee-service/bin/apigee-service edge-management-ui uninstall

To uninstall the base Classic UI (shoehorn):

/opt/apigee/apigee-service/bin/apigee-service edge-ui uninstall

To remove all Edge components from the node:

Stop all Edge services running on the machine:

/opt/apigee/apigee-service/bin/apigee-all stop

Clear the yum cache:
```
sudo yum clean all
```

Remove all the Apigee RPMs:

sudo rpm -e $(rpm -qa | egrep "(apigee-|edge-)")

Remove the installation root directory:
```
sudo rm -rf /opt/apigee
```