Upgrade the portal

This procedure describes how to upgrade an existing Apigee Developer Services portal (or simply, the portal) on-premise installation.

Determine the correct update procedure

The procedure that you use to update the portal is based on your current installation:

If your installation uses Nginx/Postgres, then use Upgrading a portal using RPMs below.
If your installation uses Apache/MySQL or Apache/MariaDB, then see Convert a tar-based portal to an RPM-based portal.

Determine your current installation type

If you are unsure about your current installation type, use the following command to determine it:

```
ls /opt
```
If you are using Nginx/Postgres, you will see the following directories: /opt/apigee and /opt/nginx.

If you are using Apache/MySQL or Apache/MariaDB, then these directories should not be present.

/opt/apigee/apigee-service/bin/apigee-all status

If you are using Nginx/Postgres, you will see the following output:

+ apigee-service
apigee-drupal-devportal status
OK: apigee-drupal-devportal is up and running
+ apigee-service apigee-lb status
apigee-service: apigee-lb: OK
+ apigee-service apigee-postgresql status
apigee-service: apigee-postgresql: OK

```
apachectl -S
```
If you are using Apache/MySQL or Apache/MariaDB, then this command should return the web root directory of the portal, in the form:
```
*:80
192.168.56.102 (/etc/httpd/conf/vhosts/devportal.conf:1)
```

Default installation directory

The upgrade process assumes that the portal was installed at:

4.17.05 and later: /opt/apigee/apigee-drupal/wwwroot
Prior to 4.17.05: /opt/apigee/apigee-drupal (Nginx) or /var/www/html (Apache)

If you did not install the portal in the default directory, modify the paths in the procedure below to use your installation directory.

Supported upgrade versions

This upgrade procedure is supported on portal versions OPDK-17-01.x and later.

To determine your portal version, open the following URL in a browser:

http://yourportal.com/buildInfo

NOTE: If for some reason you removed the buildInfo file, then you can determine the version from the profiles/apigee/apigee.info file. The default install location is /var/www/html/profiles/apigee/apigee.info, but you might have changed it at install time if you installed the portal in a directory other than /var/www/html. The apigee.info file contains a line in the form below containing the version:

version = "OPDK-4.17.05"

Before you update

For existing installations, if you have modified any code in Drupal core or in any non-custom modules, your modifications will be overwritten. This includes, among other things, any changes you may have made to .htaccess. You should assume that anything outside the /sites directory is owned by Drupal. An exception to this rule is robots.txt; if this file exists in the web root, it will be preserved for you.

Before proceeding with the installation, make a backup of your entire Drupal web root directory. After performing the installation steps described below, you can restore your customizations from the backup.

Upgrade a portal using RPMs

To update the portal RPM on a node:

Change to the Drupal directory, /opt/apigee/apigee-drupal by default:
```
cd /opt/apigee/apigee-drupal
```
Back up your Drupal database instance. The pg_dump command creates a copy of the database:
```
pg_dump --dbname=devportal --host=host_IP_address --username=drupaladmin
  --password --format=c > /tmp/portal.dmp
```
Where:
- devportal is the database name as specified by the PG_NAME property in the portal installation configuration file.
- host_IP_address is the IP address of the portal node.
- drupaladmin is the Postgres username used by the portal to access the database as specified by the DRUPAL_PG_USER property in the portal installation configuration file.
You are prompted for the Postgres user password as defined by the DRUPAL_PG_PASS property in the portal installation configuration file.

If you later want to restore from the backup, use the following command:
```
pg_restore --clean --dbname=devportal --host=localhost  --username=apigee < /tmp/portal.dmp
```
Make a backup of your entire Drupal web root directory. The default install location is /opt/apigee/apigee-drupal, but you might have changed it.
If you are unsure of the location of this directory, use the drush status command or the Configuration > Media > File entry in the Drupal menu to determine the location of the public file system and private file system path (for the next step).
TIP: Before backing up, check if the target of your backup is a soft link (or symbolic link) to the actual files. To do this, look for the file type l when you list the contents of a directory. In the following example, the second and fourth directories are symbolic links (the file type is indicated at the beginning of the permissions list):
```
ls -l /opt/apigee
drwxr-xr-x. 16 apigee   apigee  195 Jan 29 15:49 edge-qpid-server-4.19.06-0.0.20013
lrwxrwxrwx.  1 apigee   apigee   41 Jan 12 08:18 edge-router -> /opt/apigee/edge-router-4.19.06-0.0.20013
drwxr-xr-x. 15 apigee   apigee  195 Jan 29 15:50 edge-router-4.19.06-0.0.20013
lrwxrwxrwx.  1 apigee   apigee   37 Jan  9 17:13 edge-ui -> /opt/apigee/edge-ui-4.19.06-0.0.20115
```
If the target you want to back up is a soft link, then you should dereference the links to back up the actual content. How you do this depends on the tool that you use to perform the back up. For example, if you use tar, use the -h option, as the following example shows:
```
tar -hcfz /etc/my-drupal-backup.tar.gz /opt/apigee/apigee-drupal
```
Make a backup of the files in /opt/apigee/data/apigee-drupal-devportal/private.
Set Drupal to maintenance mode:
1. Select Configuration in the Drupal menu.
2. On the Configuration page, select Maintenance mode under Development.
3. Select the Put site into maintenance mode box.
4. Enter a message users see during maintenance.
5. Select Save configuration.
Disable SELinux as described in Install the Edge apigee-setup utility.
Change to the /opt directory:
```
cd /opt
```
For an upgrade on a server with an Internet connection:
1. Download the Edge 4.19.06 bootstrap_4.19.06.sh file to /tmp/bootstrap_4.19.06.sh:
```
curl https://software.apigee.com/bootstrap_4.19.06.sh -o /tmp/bootstrap_4.19.06.sh
```
2. Install the Edge 4.19.06 apigee-service utility and dependencies:
```
sudo bash /tmp/bootstrap_4.19.06.sh apigeeuser=uName apigeepassword=pWord
```
  Where uName and pWord are the username and password you received from Apigee. If you omit pWord, you will be prompted to enter it.
  
  By default, the installer checks to see that you have Java 1.8 installed. You can use the "C" option to continue without installing Java.
For an upgrade on a server with no Internet connection:
1. Create a local 4.19.06 repo as described in Create a local Apigee repository.
  NOTE: If you already have an existing repo, you can add the 4.19.06 repo to it as described in "Update a local Apigee repository" at Install the Edge apigee-setup utility.
2. To install apigee-service from a .tar file:
  1. On the node with the local repo, use the following command to package the local repo into a single .tar file named /opt/apigee/data/apigee-mirror/apigee-4.19.06.tar.gz:
```
/opt/apigee/apigee-service/bin/apigee-service apigee-mirror package
```
  2. Copy the .tar file to the node where you want to update Edge. For example, copy it to the /tmp directory on the new node.
  3. On the new node, untar the file to the /tmp directory:
```
tar -xzf apigee-4.19.06.tar.gz
```
    This command creates a new directory, named repos, in the directory containing the .tar file. For example /tmp/repos.
  4. Install the Edge apigee-service utility and dependencies from /tmp/repos:
```
sudo bash /tmp/repos/bootstrap_4.19.06.sh apigeeprotocol="file://" apigeerepobasepath=/tmp/repos
```
    Notice that you include the path to the repos directory in this command.
3. To install apigee-service using the Nginx webserver:
  1. Configure the Nginx web server as described in "Install from the repo using the Nginx webserver" at Install the Edge apigee-setup utility.
  2. On the remote node, download the Edge bootstrap_4.19.06.sh file to /tmp/bootstrap_4.19.06.sh:
```
/usr/bin/curl http://uName:pWord@remoteRepo:3939/bootstrap_4.19.06.sh
  -o /tmp/bootstrap_4.19.06.sh
```
    Where uName and pWord are the username and password you set above for the repo, and remoteRepo is the IP address or DNS name of the repo node.
  3. On the remote node, install the Edge apigee-service utility and dependencies:
```
sudo bash /tmp/bootstrap_4.19.06.sh apigeerepohost=remoteRepo:3939
  apigeeuser=uName apigeepassword=pWord apigeeprotocol=http://
```
    Where uName and pWord are the repo username and password.

Use apigee-service to update the apigee-setup utility:

/opt/apigee/apigee-service/bin/apigee-service apigee-setup update

Run the update utility on your Postgres node:
```
/opt/apigee/apigee-setup/bin/update.sh -c ps -f configFile
```
Where configFile is the configuration file that you used to install the Postgres database. The only requirement on the config file is that the configuration file must be accessible or readable by the "apigee" user.

Remove the PHP RPMs but not the Apigee Drupal Devportal RPM dependencies by executing the following command:

rpm -ev --nodeps $(rpm -qa | grep php | awk '{printf "%s ", $1}')

This command does the following:

rpm -ev --nodeps removes the RPMs but not their dependencies.
rpm -qa builds the list of RPMs to remove.
grep php searches for all PHP RPMs.
awk '{printf "%s ", $1}' prints out the RPM names.

Why do this?

OPDK v4.19.06 and later have new versions of PHP which have new RPM names. Due to this, you must remove the earlier version of PHP without removing the dependencies before upgrading the portal.

If you do not follow this step, the update utility will return dependency conflicts like the following during the next step:

Error: php72u-pdo conflicts with php70u-pdo-7.0.32-1.ius.centos7.x86_64
Error: php72u-process conflicts with php70u-process-7.0.32-1.ius.centos7.x86_64
Error: php72u-gd conflicts with php70u-gd-7.0.32-1.ius.centos7.x86_64
Error: php72u-cli conflicts with php70u-cli-7.0.32-1.ius.centos7.x86_64
Error: php72u-common conflicts with php70u-common-7.0.32-1.ius.centos7.x86_64
Error: php72u-mbstring conflicts with php70u-mbstring-7.0.32-1.ius.centos7.x86_64
Error: php72u-fpm conflicts with php70u-fpm-7.0.32-1.ius.centos7.x86_64
Error: php72u-mysqlnd conflicts with php70u-mysqlnd-7.0.32-1.ius.centos7.x86_64
Error: php72u-pgsql conflicts with php70u-pgsql-7.0.32-1.ius.centos7.x86_64
Error: php72u-json conflicts with php70u-json-7.0.32-1.ius.centos7.x86_64
Error: php72u-ldap conflicts with php70u-ldap-7.0.32-1.ius.centos7.x86_64
Error: php72u-xml conflicts with php70u-xml-7.0.32-1.ius.centos7.x86_64
 You could try using --skip-broken to work around the problem
 You could try running: rpm -Va --nofiles --nodigest

You must remove the PHP RPMs but not their dependencies so that you do not remove the Apigee Drupal Devportal RPMs.

TIP: To validate which RPMs will be removed, you can execute just the following portion of the command:

rpm -qa | grep php | awk '{printf "%s ", $1}'

To improve the appearance of the output, you can change the formatting string to print out a newline after each RPM, as the following example shows:

rpm -qa | grep php | awk '{printf "%s\n", $1}'

Run the update utility on your node to update the portal:
```
/opt/apigee/apigee-setup/bin/update.sh -c dp -f configFile
```
Where configFile is the configuration file that you used to install the portal. The only requirement on the config file is that the configuration file must be accessible or readable by the "apigee" user.
Run Drupal's update.php script by opening the following URL in a browser window:
```
http://portal_IP_DNS:8079/update.php
```
Disable maintenance mode:
1. Select Configuration in the Drupal menu.
2. On the Configuration page, select Maintenance mode under Development.
3. Deselect the Put site into maintenance mode box.
4. Select Save configuration.

Note that the root directory after the update is:

/opt/apigee/apigee-drupal/wwwroot

The upgrade is now complete. If the Apigee update utility downgraded your version of Drupal, you might need to re-run the Drupal upgrade utility. For more information, see Re-run the Drupal upgrade.

Re-run the Drupal upgrade

If running the Apigee update utility to upgrade Edge for Private Cloud actually results in a downgrade of your Drupal version, reinstall the Drupal upgrade. This might be the case if you upgraded only Drupal in between Private Cloud updates.

For example:

You were running version 4.18.05 of Edge for Private Cloud, which included Drupal 7.59.
You upgraded Drupal to 7.64 due to a required security update.
You are now upgrading Private Cloud to 4.19.01, which includes Drupal 7.61.

As this case illustrates, the Drupal version used by the Apigee update utility might not reference the latest Drupal upgrade. As a result, you must now re-run your Drupal upgrade to return your Drupal installation to the later version.