Install the portal

Edge for Private Cloud v4.19.01

Before you install Apigee Developer Services portal (or simply, the portal), 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.

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.

Test your connection
Remove pre-7.0 versions of PHP
Install Postgres
Install the portal
Ensure Update manager is enabled
(Optional) Configure Apache Solr
(Optional) Install SmartDocs
(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:

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.

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

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:

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

To install the portal:

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.
  The configuration file must be accessible or readable by the "apigee" user.
- -p dp instructs the setup script to install the portal.

To verify that the portal installation was successful:

Navigate to the portal home page at http://localhost:8079 or to the DNS name of your portal.
Log in to the portal using the administrator credentials that you set in the portal configuration file.
Select Reports > Status Report in the Drupal menu to ensure that you can see the current status of the portal.
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:

Log in to your portal as a user with admin or content creation privileges.
Select Modules in the Drupal menu.
Enable the Apache Solr Framework module and the Apache Solr Search module.
Save your changes.
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:

Log in to your portal as a user with admin or content creation privileges.
Select Configuration > Development > JQuery Update in the Drupal menu.
Click Performance in the left navigation.
In the JQuery and JQuery UI CDN drop-down select None.
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:

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` for Drupal by following these steps: Create the directory `/opt/apigee/data/apigee-drupal-devportal/sites/default/includes` if it does not exist. Create a file named `settings.php` in that directory. Add the following to the `settings.php` file: /** * Base URL (optional). * * If Drupal is generating incorrect URLs on your site, which could * be in HTML headers (links to CSS and JS files) or visible links * on pages (such as in menus), uncomment the Base URL statement * below (remove the leading hash sign) and fill in the absolute URL * to your Drupal installation. * * You might also want to force users to use a given domain. * See the .htaccess file for more information. * * Examples: * $base_url = 'http://www.example.com'; * $base_url = 'http://www.example.com:8888'; * $base_url = 'http://www.example.com/drupal'; * $base_url = 'https://www.example.com:8888/drupal'; * * It is not allowed to have a trailing slash; Drupal will add it * for you. */ # $base_url = 'http://www.example.com/'; // NO trailing slash! $base_url = ‘http://www.example.com’; Change the last `$base_url` line to be the hostname of your site. Save the file. Note that you can put any other settings from `/opt/apigee/data/apigee-drupal-devportal/ sites/default/default.settings.php` in this file. For more information about the `$base_url` property, see the following: https://codeburst.io/security-for-drupal-and-related-server-software-3c979b041595 https://www.drupal.org/node/1992030
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.