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

Edge for Private Cloud v4.18.05

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:

  1. Install the RPM-based 4.18.05 version of the 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. Log in 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", 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.

  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 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.
    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 the 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 that the copied files have proper ownership:
        chown -R apigee:apigee /opt/apigee/apigee-drupal/wwwroot/sites/
      6. 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
      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. 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.

  12. 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.
  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.