Developer Services portal installation

Edge for Private Cloud v. 4.17.05

Before you install, ensure that:

  • 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.
  • 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.
  • Yum is installed.

Installation overview

After you install the Edge the apigee-setup utility on a node, use that utility to install the portal on the node. The apigee-setup utility has the form:

> sudo /opt/apigee/apigee-setup/bin/setup.sh -p component -f configFile

Pass a configuration file to the apigee-setup utility that contains the information about the installation. If the configuration file is missing any required information, the apigee-setup utility prompts you to enter it on the command line.

The only requirement is that the configuration file must be accessible or readable by the "apigee" user.

For example, use the following command to install the portal:

> sudo /opt/apigee/apigee-setup/bin/setup.sh -p dp -f myConfig

See Install the Edge apigee-setup utility for more.

Creating a 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=pWord 
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=pWord 

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

# You must configure the SMTP server used by the portal. 
# 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 

# Use SSL for SMTP: 'y' or 'n' (default). 
SMTPSSL="n" 

# 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=yourEmailPassword

1. Test your connection to Apigee Edge

Test your connection to the Edge management server by executing the following cURL command from a command prompt 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.

Make 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, this command 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>

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 config file for Postgres, as shown below:

    # 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 configFile

    The “-p pdb” option specifies to install Postgre.

    The configuration file must be accessible or readable by the "apigee" user.

4. Install the portal

To install the portal:

  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. Ensure that you have installed Postgres, either Postgres standalone or as part of installing Edge.
  3. At the command prompt, run the setup script:
    > /opt/apigee/apigee-setup/bin/setup.sh -p dp -f configFile

    The “-p dp” option specifies to install the portal.

    The configuration file must be accessible or readable by the "apigee" user.
  4. Navigate to the portal home page at http://localhost:8079 or to the DNS name of your portal.
  5. Log in to the portal using the administrator credentials that you set in the config file.

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 Developer 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 Developer Services 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. What next?

Your next steps after you install the Developer Services portal are to configure and customize it for your specific requirements. The documentation on the Apigee web site contains all of the information on configuring, styling, and managing a portal. Access the documentation at http://apigee.com/docs/developer-services/content/what-developer-portal.

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:

Task

Description

Customizing the theme

The theme defines the appearance of the portal, including colors, styling, and other visual aspects.

Customize the appearance

The home page includes the main menu, welcome message, header, footer, and title.

Add and manage user accounts

The registration process controls how new developers register an account on the portal. For example, do new developers get immediate access to the portal, or do they have to be verified by an administrator. This process also controls how a portal administrator is notified when a new account is created.

Configuring email

The portal sends emails in response to certain events. For example, when a new developer registers on the portal and when a developer loses their password.

Add and manage user accounts

Add a Terms & Conditions page that developers must accept before being allowed to access the portal.

Add and manage user accounts

The portal implements a role-based authorization model. Before allowing developers to register, define the permissions and roles used by the portal.

Add blog and forum posts

The portal has built-in support for blogs and threaded forums. Define the permissions required to view, add, edit, and delete blog and forum posts.

Ensure you are doing database backups

Ensure that you are backing up the Drupal database. Note that because every installation is different, it is up to you to determine how best to back up the database.

Note: The Backup and Migrate module is not compatible with Postgres databases.

See also How to Perform a Backup.

Set up a hostname

If you do not set up a hostname in your DNS server, you can always access the site via the server’s IP address. If you want to use a hostname, you can configure DNS for the server, which should work correctly without any other configuration on a basic setup.

If you set up a load balancer or are getting incorrect URLs on your site for some other reason, you can set $base_url in the Dev Portal settings.php file, which by default is located in the /opt/apigee/apigee-drupal/wwwroot/sites/default directory.

Custom development You may also want to extend your portal's capabilities with custom code outside of your theme. To do this, create your own Drupal module as described in Drupal's module development topics, and put the module in the /sites/all/modules directory.