Convert a tar-based portal to an RPM-based portal

The 4.18.05 release of Apigee Developer Services portal (or simply, the portal) does not let you update a previous tar-based version of the portal. You can only directly update an RPM-based version of the portal to 4.18.05.

However, you can convert a tar-based version of the portal to an 4.18.05 RPM-based instance of the portal. As part of this process, you migrate the MySQL/MariaDB of the existing portal to a Postgres database. Once converted, your portal remains as an RPM-based portal.

You can migrate many previous versions of the tar-based portal to an RPM-based portal, including versions 4.16.09 and 4.17.01, not just version 4.17.05. The only requirements is that the portal is running Drupal 7 or later. To check your version of Drupal, select Reports > Status Reports in the Drupal menu. The version of Drupal appears in the first row of the output.

The high-level steps that you use to migrate from a tar-based portal to an RPM-based portal are:

Install the RPM-based 4.18.05 version of the portal on a new node.
Create a new Postgres database on the RPM-based portal.
Migrate the portal database from the tar-based portal.
Copy all accessory file from the tar-based portal to the RPM-based portal.
Update DNS entries to point to the new RPM-based portal.
Note that the RPM-based version of the portal uses port 8079 by default, while the tar-based version uses port 80. Make sure you use the correct port number in your DNS entry. See Set the HTTP port used by the portal for information on using a different port.

New default installation directory after conversion

After updating an installation that now uses NGINX/Postgres, the root directory changed from:

/opt/apigee/apigee-drupal

to:

/opt/apigee/apigee-drupal/wwwroot

Portal conversion procedure

To convert the portal to an RPM-based installation:

Install the RPM-based 4.18.05 version of the portal on a different node from your tar-based portal.
On the RPM-based portal, create a new Postgres database. Later, you migrate the database from the tar-based portal to this new database:
1. Log in to psql:
```
psql -h localhost -p 5432 -U apigee
```
  Enter your Postgres password as defined by the PG_PWD property in the portal config file.
2. Create a new Postgred database:
```
CREATE DATABASE newportaldb;
```
3. Exit psql:
```
\q
```

On the tar-based portal, remove old modules that are no longer used:

cd /var/www/html
drush sql-query --db-prefix "DELETE from {system} where name = 'apigee_account' AND type = 'module';"
drush sql-query --db-prefix "DELETE from {system} where name = 'apigee_checklist' AND type = 'module';"
drush sql-query --db-prefix "DELETE from {system} where name = 'apigee_sso_ui' AND type = 'module';"

On the tar-based portal, Install and configure the Migrator Drupal module:

```
cd /tmp 
```

wget https://ftp.drupal.org/files/projects/dbtng_migrator-7.x-1.4.tar.gz

gunzip /tmp/dbtng_migrator-7.x-1.4.tar.gz

tar -xvf /tmp/dbtng_migrator-7.x-1.4.tar --directory /var/www/html/sites/all/modules

Log in to the portal as an admin.
Select Modules in the Drupal menu.
Enable the DBTNG Migrator module.
Save the configuration.

On the tar-based portal, edit /var/www/html/sites/default/settings.php to add a second database configuration pointing to the newly created database on the RPM-based portal. The current database configuration is named "default". Name your new configuration "custom", as the following example shows:

$databases = array (
  'default' =>
  array (
    'default' =>
    array (
      'database' => 'devportal',
      'username' => 'devportal',
      'password' => 'devportal',
      'host' => 'localhost',
      'port' => '',
      'driver' => 'mysql',
      'prefix' => '',
    ),
  ),
  'custom' =>
  array (
    'default' =>
    array (
      'database' => 'newportaldb',
      'username' => 'apigee',
      'password' => 'postgres',
      'host' => '192.168.168.100',
      'port' => '5432',
      'driver' => 'pgsql',
      'prefix' => '',
    )
  )
);

Where host and port specify the IP address and port of the Postgres server. Postgres uses port 5432 for connections.

On the tar-based portal, install the Postgres driver:
1. Use Yum to install the driver:
```
yum install php-pdo_pgsql
```
2. Edit /etc/php.ini to add the following line anywhere in the file:
```
extension=pgsql.so
```
3. Restart Apache:
```
service httpd restart
```
On the tar-based portal, migrate the portal database to the RPM-based portal:
1. Log in to the portal as an admin.
2. Select Structure->Migrator in the Drupal menu.
3. Choose your origin database on the tar-based portal, default, and the destination database, custom, based on settings.php file shown above.
4. Click Migrate. The tar-based database is migrated to the RPM-based database.

Copy the sites directory from the tar-based server to the RPM-based server. The paths shown in the following steps are based on default paths. Modify them as necessary for your installation.

On the tar-based portal, bundle the /var/www/html/sites directory:
```
cd /var/www/html/sites
tar -cvzf /tmp/sites.tar.gz .
```
Copy /tmp/sites.tar.gz to /opt/apigee/apigee-drupal/wwwroot/sites on the RPM-based server.

Unbundle sites directory, but do not overwrite important files.

Backup the settings.php file:

sudo cp /opt/apigee/apigee-drupal/wwwroot/sites/default/settings.php
  /opt/apigee/apigee-drupal/wwwroot/sites/default/settings.bak.php

Backup the existing files directory:

sudo mv /opt/apigee/apigee-drupal/wwwroot/sites/default/files
  /opt/apigee/apigee-drupal/wwwroot/sites/default/files_old

Backup the existing sites directory:

tar -cvzf /tmp/sites_old.tar.gz /opt/apigee/apigee-drupal/wwwroot/sites

Unzip and untar the sites directory from the tar-based server:

gunzip /opt/apigee/apigee-drupal/wwwroot/sites/sites.tar.gz
tar -xvf /opt/apigee/apigee-drupal/wwwroot/sites/sites.tar

Make sure that the copied files have proper ownership:

chown -R apigee:apigee /opt/apigee/apigee-drupal/wwwroot/sites/

Restore the settings.php file:

sudo cp /opt/apigee/apigee-drupal/wwwroot/sites/default/settings.bak.php
  /opt/apigee/apigee-drupal/wwwroot/sites/default/settings.php

Move private files to new location:

cp -r /opt/apigee/apigee-drupal/wwwroot/sites/default/files/private/* /opt/apigee/data/apigee-drupal-devportal/private
rm -rf /opt/apigee/apigee-drupal/wwwroot/sites/default/files/private
chown -R apigee:apigee /opt/apigee/data/apigee-sap-drupal-devportal/private

On the tar-based portal, only if you changed the path to the web root directory on the tar-based portal from the default path of /var/www/html: run drush status and look at files path and private files path:
```
cd /var/www/html
drush status
```
If files/private files are not under the sites directory, copy them to the RPM-based server as shown above.

On the RPM-based portal, update /opt/apigee/apigee-drupal/wwwroot/sites/default/settings.php to set the properties of the default database:

vi /opt/apigee/apigee-drupal/wwwroot/sites/default/settings.php

Set the default database description in settings.php:

$databases = array (
  'default' =>
  array (
    'default' =>
    array (
      'database' => 'newportaldb',
      'username' => 'apigee',
      'password' => 'postgres',
      'host' => 'localhost', 'port' => '5432',
      'driver' => 'pgsql',
      'prefix' => '',
    )
  )
);

Where database specifies the new database you created, username and password are as defined for the custom database on the tar-based portal, and prefix is empty.

On the RPM-based portal, the RPM-based version of the portal contains fewer Drupal modules than the tar-based version. After you migrate to the RPM-based portal, you must check for any missing modules and install them as necessary.
1. Install the Drupal missing_module used to detect missing modules:
```
cd /opt/apigee/apigee-drupal/wwwroot
drush dl missing_module
drush en missing_module
```
2. Log in to the RPM-based portal as an admin.
3. Select Reports > Status reports in the Drupal menu and check for any missing modules.
4. Use that report to install any missing modules, or use the following commands:
```
cd /opt/apigee/apigee-drupal/wwwroot
drush dl <moduleA> <moduleB> ...
drush en <moduleA> <moduleB> ...
```
5. After you enable all the modules, make sure the files are owned by the apigee user:
```
chown -LR apigee:apigee /opt/apigee/apigee-drupal/wwwroot
```
  For more on file permissions, see https://www.drupal.org/node/244924.
On the RPM-based portal, run update.php in a browser to remove any errors on missing modules:
1. Log in to the RPM-based portal as an admin.
2. In the browser, navigate to the following URL:
```
http://portal_IP_or_DNS:8079/update.php
```
  Where portal_IP_or_DNS is the IP address or domain name of the RPM-based portal.
3. Follow the screen prompts.
Update DNS entries to point to your new RPM-based portal.

Note that the RPM-based version of the portal uses port 8079 by default, while the tar-based version uses port 80. Make sure you use the correct port number in your DNS entry. See Set the HTTP port used by the portal for information on using a different port.

The conversion is complete.

When the contents of the file settings.php for a new RPM-based portal are different from those for a tar-based portal, you need to update the file

/opt/apigee/apigee-drupal-devportal-opdk_version/source/conf/settings.php

with the new contents to prevent it from being restored to the old settings.