Install the portal

Edge for Private Cloud v4.19.01

Before you install Apigee Developer Services portal (or simply, the portal), ensure that:

1. You install Postgres before installing the portal. You can either install Postgres as part of installing Edge, or install Postgres standalone for use by the portal.
   • If you install Postgres standalone, it can be on the same node as the portal.
   • If you are connecting to Postgres installed as part of Edge, and Postgres is configured in master/standby mode, specify the IP address of the master Postgres server.
2. You are performing the install on the 64-bit version of a supported version of Red Hat Enterprise Linux, CentOS, or Oracle. See the list of supported versions at Supported software and supported versions.
3. Yum is installed.

The installer only includes Drupal-contributed modules that are required by the Apigee Developer Services portal (or simply, the portal). For information about installing other contributed modules, see Extending Drupal 7.

Installation overview

To install the portal, you will perform the following steps. Each of these steps is described in more detail in the sections that follow.

1. Test your connection
2. Remove pre-7.0 versions of PHP
3. Install Postgres
4. Install the portal
5. Ensure Update manager is enabled
6. (Optional) Configure Apache Solr
7. (Optional) Install SmartDocs
8. (Optional) Configure JQuery

Deprecation of the SMTPSSL property

In previous releases, you used the SMTPSSL property to set the protocol used by the SMTP server connected to the portal. That property has been deprecated.

You now use the SMTP_PROTOCOL property, instead of the SMTPSSL property, to set the protocol used by the SMTP server connected to the portal. The valid values are: "standard", "ssl", or "tls".

Create a portal configuration file

Shown below is an example silent configuration file for a portal installation. Edit this file as necessary for your configuration. Use the -f option to setup.sh to include this file.

IP1=IPorDNSnameOfNode

# Must resolve to IP address or DNS name of host - not to 127.0.0.1 or localhost.
HOSTIP=$(hostname -i)

# Specify the name of the portal database in Postgres.
PG_NAME=devportal

# Specify the Postgres admin credentials.
# The portal connects to Postgres by using the 'apigee' user.
# If you changed the Postgres password from the default of 'postgres'
# then set PG_PWD accordingly.
# If connecting to a Postgres node installed with Edge,
# contact the Edge sys admin to get these credentials.
PG_USER=apigee
PG_PWD=postgres

# The IP address of the Postgres server.
# If it is installed on the same node as the portal, specify that IP.
# If connecting to a remote Postgres server,specify its IP address.
PG_HOST=$IP1

# The Postgres user credentials used by the portal
# to access the Postgres database,
# This account is created if it does not already exist.
DRUPAL_PG_USER=drupaladmin
DRUPAL_PG_PASS=portalSecret

# Specify 'postgres' as the database.
DEFAULT_DB=postgres

# Specify the Drupal admin account details.
# DO NOT set DEVPORTAL_ADMIN_USERNAME=admin.
# The installer creates this user on the portal.
DEVPORTAL_ADMIN_FIRSTNAME=firstName
DEVPORTAL_ADMIN_LASTNAME=lastName
DEVPORTAL_ADMIN_USERNAME=userName
DEVPORTAL_ADMIN_PWD=PORTAL_ADMIN_PASSWORD
DEVPORTAL_ADMIN_EMAIL=foo@bar.com

# Edge connection details.
# If omitted, you can set them in the portal UI.
# Specify the Edge organization associated with the portal.
EDGE_ORG=edgeOrgName

# Specify the URL of the Edge management API.
# For a Cloud based installation of Edge, the URL is:
# https://api.enterprise.apigee.com/v1
# For a Private Cloud installation, it is in the form:
# http://ms_IP_or_DNS:8080/v1 or
# https://ms_IP_or_DNS:TLSport/v1
MGMT_URL=https://api.enterprise.apigee.com/v1

# The org admin credentials for the Edge organization in the form
# of Edge emailAddress:pword.
# The portal uses this information to connect to Edge.
DEVADMIN_USER=orgAdmin@myCorp.com
DEVADMIN_PWD=ORG_ADMIN_PASSWORD

# The PHP port.
# If omitted, it defaults to 8888.
PHP_FPM_PORT=8888

# Optionally configure the SMTP server used by the portal.
# If you do, the properties SMTPHOST and SMTPPORT are required.
# The others are optional with a default value as notated below.
# SMTP hostname. For example, for the Gmail server, use smtp.gmail.com.
SMTPHOST=smtp.gmail.com

# Set the SMTP protocol as "standard", "ssl", or "tls",
# where "standard" corresponds to HTTP.
# Note that in previous releases, this setting was controlled by the
# SMTPSSL property. That property has been deprecated.
SMTP_PROTOCOL="standard"

# SMTP port (usually 25).
# The value can be different based on the selected encryption protocol.
# For example, for Gmail, the port is 465 when using SSL and 587 for TLS.
SMTPPORT=25

# Username used for SMTP authentication, defaults is blank.
SMTPUSER=your@email.com

# Password used for SMTP authentication, default is blank.
SMTPPASSWORD=YOUR_EMAIL_PASSWORD

1. Test your connection to Apigee Edge

Test your connection between the server you're going to install the portal on and the Edge management server by executing the following curl command on the portal server:

curl -u EMAIL:PASSWORD http://ms_IP_or_DNS:8080/v1/organizations/ORGNAME

or:

curl -u EMAIL:PASSWORD https://ms_IP_or_DNS:TLSPort/v1/organizations/ORGNAME

Where EMAIL and PASSWORD are the email address and password of the administrator for ORGNAME.

Be sure to specify the hostname and port number specific to your installation of Edge. Port 8080 is the default port used by Edge. If you are connecting to an organization in the cloud, then the request URL is: https://api.enterprise.apigee.com/v1/organizations/ORGNAME.

If successful, curl returns a response similar to the following:

{
  "createdAt" : 1348689232699,
  "createdBy" : "USERNAME",
  "displayName" : "cg",
  "environments" : [ "test", "prod" ],
  "lastModifiedAt" : 1348689232699,
  "lastModifiedBy" : "foo@bar.com",
  "name" : "cg",
  "properties" : {
    "property" : [ ]
  },
  "type" : "trial"
}

2. Remove pre-7.0 versions of PHP

The install script checks for pre-7.0 versions of PHP on the system before starting the installation. If pre-7.0 versions of PHP exist, the following warning message displays:

The following packages present on your system conflict with software we are
about to install. You will need to manually remove each one, then re-run this install script.

php
php-cli
php-common
php-gd
php-mbstring
php-mysql
php-pdo
php-pear
php-pecl-apc
php-process
php-xml

Remove the PHP packages using the following command:

yum remove package_name

If you are not sure if PHP is installed on your server, use the following command:

rpm -qa | grep -i php

Note that the portal uses PHP version 4.18.01-0.0.49. This is not intended to match the version number of Apigee Edge for Private Cloud.

3. Install Postgres

The portal requires Postgres to be installed before you can install the portal. You can either install Postgres as part of installing Edge, or install Postgres standalone for use by the portal.

• If you are connecting to Postgres installed as part of Edge, and Postgres is configured in master/standby mode, specify the IP address of the master Postgres server.
• If you install Postgres standalone, it can be on the same node as the portal.

For information on installing Postgres as part of installing Edge, see Install Edge components on a node.

To install Postgres standalone:

1. Install the Edge apigee-setup utility on the node using the internet or non-internet procedure. See Install the Edge apigee-setup utility for more.
2. Create a Postgres configuration file, as the following example shows:

   # Must resolve to IP address or DNS name of host - not to 127.0.0.1 or localhost
   HOSTIP=$(hostname -i)
   
   # The pod and region of Postgres. Use the default values shown below.
   MP_POD=gateway
   REGION=dc-1
   
   # Set the Postgres password. The default value is 'postgres'.
   PG_PWD=postgres

3. At the command prompt, run the setup script to install Postgres:

   /opt/apigee/apigee-setup/bin/setup.sh -p pdb -f postgres_config_file

   The -p pdb option specifies to install Postgre. The configuration file must be accessible or readable by the "apigee" user.

4. Install the portal

Before you can install the portal, be sure that you have done the following as described in 3. Install Postgres:

1. Install the Edge apigee-setup utility on portal's node
2. Install Postgres, either Postgres standalone or as part of installing Edge

To install the portal:

1. At the command prompt, run the setup script:

   /opt/apigee/apigee-setup/bin/setup.sh -p dp -f configFile

   Where:

   • configFile is the portal configuration file as described in Create a portal configuration file.
   • -p dp instructs the setup script to install the portal.

To verify that the portal installation was successful:

1. Navigate to the portal home page at http://localhost:8079 or to the DNS name of your portal.
2. Log in to the portal using the administrator credentials that you set in the portal configuration file.
3. Select Reports > Status Report in the Drupal menu to ensure that you can see the current status of the portal.
4. Be sure that the Management Server connection was successful. If it was not:
   1. Navigate to the portal Connection Configuration page (for example, http://portal_IP:8079/admin/config/devconnect).
   2. Click the Test Connection button. If the connection is successful, you are done. If the connection fails, continue.
   3. Check the endpoint and authentication settings:
      • Management API endpoint URL: Check that the protocol (HTTP or HTTPS), IP or DNS name, and port number are correct; for example:

        http://10.10.10.10:8080/v1

      • Endpoint authenticated user: The organization admin's username.
      • Authenticated user's password: The organization admin's password.

      The default values reflect the settings in your portal configuration file that you created during the installation process.

      These values should match the ms_IP_or_DNS, email, and password values you used in step 1: Test your connection to Apigee Edge. The username and password should also match the values of the USER_NAME and USER_PWD properties in the onboarding configuration file, or the credentials of any user whose role is Organization Administrator.

   4. After you successfully connect to the Management Server, click the Save configuration button at the bottom of the page to save your changes.

5. Ensure that the Update manager module is enabled

To receive notifications of Drupal updates, ensure that the Drupal Update manager module is enabled. From the Drupal menu, select Modules and scroll down to the Update manager module. If it is not enabled, enable it.

Once enabled, you can see the available updates by using the Reports > Available Updates menu item. You can also use the following Drush command:

drush pm-info update

You have to run this command from the root directory of the site. By default, the portal is installed at /opt/apigee/apigee-drupal/wwwroot. Therefore, you should first change directory to /opt/apigee/apigee-drupal/wwwroot before running the command. If you did not install the portal in the default directory, change to your installation directory.

Use the Reports > Available Updates > Settings menu item to configure the module to email you when updates are available and to set the frequency for checking for updates.

6. Configure the Apache Solr search engine (Optional)

By default, the Drupal modules that connect to the Apache Solr search engine are disabled when you install the portal. Most portals use the internal Drupal search engine, and therefore do not require the Drupal Solr modules.

If you decide to use Solr as your search engine, you must install Solr locally on your server and then enable and configure the Drupal Solr modules on the portal.

To enable the Drupal Solr modules:

1. Log in to your portal as a user with admin or content creation privileges.
2. Select Modules in the Drupal menu.
3. Enable the Apache Solr Framework module and the Apache Solr Search module.
4. Save your changes.
5. Configure Solr as described at https://drupal.org/node/1999280.

7. Install SmartDocs (Optional)

SmartDocs lets you document your APIs on the portal in a way that makes the API documentation fully interactive. However, to use SmartDocs with the portal, you must first install SmartDocs on Edge.

• If you are connecting the portal to an Edge Cloud installation, SmartDocs is already installed and no further configuration is necessary.
• If you are connecting the portal to an Edge for Private Cloud installation, you must ensure that SmartDocs is installed on Edge. For more on installing Edge and SmartDocs, see Install SmartDocs.

You must also enable SmartDocs on the portal. For more information on SmartDocs, see Using SmartDocs to document APIs.

8. Configure the JQuery Update module for non-internet installations (Optional)

If you install and use the JQuery Update module in a non-internet installation, you need to configure the module to use the local version of JQuery. If you configure the module to use a CDN for a non-internet installation, it will attempt to access the CDN and cause delays with page loading. For more information about the JQuery Update module see https://www.drupal.org/project/jquery_update.

To configure the JQuery Update module to use the local version of JQuery:

1. Log in to your portal as a user with admin or content creation privileges.
2. Select Configuration > Development > JQuery Update in the Drupal menu.
3. Click Performance in the left navigation.
4. In the JQuery and JQuery UI CDN drop-down select None.
5. Click Save configuration.

9. Next steps

The following table lists some of the most common tasks that you perform after installation, and includes links to the Apigee documentation where you can find more information: