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

Edge for Private Cloud v4.18.01

The 4.18.01 release of the Developer Services 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.01.

However, you can convert a tar-based version of the portal to an 4.18.01 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.01 version of the Developer Service 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.01 version of the Developer Service 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:
1. cd /tmp
2. wget https://ftp.drupal.org/files/projects/dbtng_migrator-7.x-1.4.tar.gz
3. gunzip /tmp/dbtng_migrator-7.x-1.4.tar.gz
4. tar -xvf /tmp/dbtng_migrator-7.x-1.4.tar --directory /var/www/html/sites/all/modules
5. Login to the portal as an admin.
6. Select Modules in the Drupal menu.
7. Enable the DBTNG Migrator module.
8. 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:

$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 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.
1. On the tar-based portal, bundle the /var/www/html/sites directory:
  > cd /var/www/html/sites
  > tar -cvzf /tmp/sites.tar.gz .
2. Copy /tmp/sites.tar.gz to /opt/apigee/apigee-drupal/wwwroot/sites on the RPM-based server.
3. Unbundle sites directory, but do not overwrite important files.
  1. 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
  2. Backup existing files directory:
    > sudo mv /opt/apigee/apigee-drupal/wwwroot/sites/default/files /opt/apigee/apigee-drupal/wwwroot/sites/default/files_old
  3. Backup the existing sites directory:
    > tar -cvzf /tmp/sites_old.tar.gz /opt/apigee/apigee-drupal/wwwroot/sites
  4. 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
  5. Make sure copied files have proper ownership:
    > chown -R apigee:apigee /opt/apigee/apigee-drupal/wwwroot/sites/
  6. Restore settings.php file:
    > sudo cp /opt/apigee/apigee-drupal/wwwroot/sites/default/settings.bak.php /opt/apigee/apigee-drupal/wwwroot/sites/default/settings.php
  7. 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. Login 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. Login 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.