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:

  1. Install the RPM-based 4.18.01 version of the Developer Service portal on a different node from your tar-based portal.
  2. 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
  3. 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';"

  4. 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.
  5. 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.
  6. 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
  7. 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.
  8. 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
  9. 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.
  10. 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.
  11. 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.
  12. 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.
  13. 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.