PreEmptive Analytics Standalone Repository User Guide

Upgrading

This section provides instructions for upgrading the Standalone Repository from 1.0 to 1.1. Please read it thoroughly before starting your upgrade process.

Architectural changes in 1.1

Of several database format changes, a notable one is to each envelope's date information. Analytics envelopes that are stored in 1.0 database may have nonsensical date information due to clients with out-of-sync system clocks. In order to correct this discrepancy, the date information used in 1.1 is the time the database itself recorded the envelope, not the time it was sent by the client.

Because this issue affects the Workbench's temp-bin cleanup process, and because the date information needed is not transmitted by Replayer 1.0, neither Workbench 1.1 nor Standalone Repository 1.1 will accept replays from earlier Standalone Repository versions. Upgrading the Standalone Repository (and Replayer) is necessary first.

Upgrade compatibility

Due to database changes, Replayer 1.0 cannot replay from Standalone Repository 1.1. When upgrading the Standalone Repository, you must also upgrade the Replayer to version 1.1.

Upgrade duration

The upgrade may take anywhere from a few minutes to a few hours. A rough estimate of the processing rate is 10-20 minutes per 1 GB of storage in MongoDB (excluding anything else in the database, e.g. the Workbench storage). This will vary based on a number of factors that are specific to your installation's hardware. The installer will give you a specific estimate before the install process begins, based on typical hardware and database sizes.

During the upgrade, the Standalone Repository endpoint will be unavailable; please schedule the upgrade accordingly.

Detailed upgrade procedures

Upgrade or install the Data Hub

Replayer 1.1 requires a local installation of the PreEmptive Analytics Data Hub, version 1.4.1 (or greater). Refer to the user guides and tutorials listed here for the installation and upgrade procedures.

Queue data upstream

Assuming that there is a Data Hub upstream from the Standalone Repository (typically the one installed on the same host), the next step is to have that Data Hub queue any data that arrives. This ensures that the Standalone Repository can be safely offline, and database operations can be safely performed, without data arriving at an unexpected time.

The easiest and least-error-prone way to have an upstream Hub queue data is to modify the destination entry in the DispatchService\Dispatch.config file (in the Hub's installation folder, e.g., C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics Data Hub) to use a TCP port that isn't actually open. So if your upstream Hub is currently pointed to http://127.0.0.1:99/endpoint, you might change the 99 to 999, which is probably not an open TCP/HTTP port.

You can check for open TCP ports by running netstat -a -n in a command prompt; look for rows whose State is LISTENING and check the port number listed in the Local Address column. Be sure to use a new port number that is not shown as LISTENING.

If you also have a Workbench installed on the same host as the Standalone Repository, you should also change its destination's port to an unused port, so that it will not receive any data and will not try to write to MongoDB.

Once the Dispatch.config file is changed and saved, you should restart the PreEmptive Analytics Data Hub Dispatch Service (from services.msc) so that it begins using the new port.

You may wish to watch the RabbitMQ queues (http://localhost:15672/#/queues, login: guest/guest) to see that data is being queued in the appropriate offline queue(s), before proceeding.

Take a backup

Please ensure you have a recent backup before continuing the rest of the upgrade process.

If you wish to have a "just before upgrade" backup, this is the time to do it.

Set Windows page file size

Per the MongoDB Production Notes, we recommend setting the Windows page file to the largest feasible multiple of 32 GB, if not already done so.

Upgrade MongoDB

Standalone Repository 1.0 required any 2.6.x version of MongoDB, but Standalone Repository 1.1 specifically requires 2.6.10 (or later in the 2.6 series). If you do not already have 2.6.10 (or greater) installed, you will need to upgrade MongoDB. Note that MongoDB 3.x is not currently supported.

To upgrade, download MongoDB 2.6 (x64) from http://www.mongodb.org/downloads. Download the zip package, not the MSI. Extract the zip to somewhere convenient.

The upgrade is a simple binary replacement:

  1. Open services.msc (Windows Services) and stop the MongoDB service.
  2. Copy all files from the bin\ subdirectory of the new/downloaded MongoDB version into the bin\ subdirectory of your MongoDB installation directory (typically c:\mongodb\).
  3. Open services.msc (Windows Services) and start the MongoDB service.

Save configurations to the side

If you have made any changes to .config files (e.g., Web.config and NLog.config) in the Standalone Repository install directory (e.g., C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics Standalone Repository), then you will need to save those files off to the side during the uninstall/reinstall process.

Uninstall 1.0 (preserving data)

To remove 1.0:

  1. Open the Programs and Features control panel, find PreEmptive Analytics Standalone Repository, and uninstall it.
    • If the uninstall process warns you that a restart will be required, you must manually restart the host after the uninstall finishes.
  2. The uninstall will leave behind any files that were added after the original install. You can delete the entire Standalone Repository install directory if you wish.

Install 1.1 (upgrading data)

After uninstalling 1.0 and, if necessary, rebooting:

  1. Copy PreEmptive.Analytics.Standalone.Repository.exe to the host machine.
  2. As an administrator, run that executable and follow the prompts.
    • We suggest using the defaults and/or any specific values that you chose during the 1.0 install, for consistency and ease of configuration.
    • Before the installation begins, an estimate of the time needed to upgrade will be displayed. Confirm you have a backup before proceeding.

Your 1.0 database will be automatically upgraded to the 1.1 format as part of the install process.

Reapply configurations

You should now reapply any configuration changes you made to the config files that you saved to the side. If you modified the default IIS endpoint or application pool you should also reapply these modifications.

Reconfigure and release the upstream queue(s)

At this point the Standalone Repository is installed and ready to resume receiving data. To allow data to come through, you must undo what you did above by modifying the upstream Data Hub to have the correct port for the Standalone Repository endpoint (default 99).

If you have a Workbench installed, you should also set its port back to the correct value (default 81 for 1.1).

Once the Dispatch.config file is changed and saved, restart the PreEmptive Analytics Data Hub Dispatch Service (from services.msc) so that it begins using the new port.

You may wish to watch the RabbitMQ queues (http://localhost:15672/#/queues, login: guest/guest) to see that data is being delivered out of the appropriate offline queue(s), before proceeding.

Upgrade the Replayer

Replaying from Standalone Repository 1.1 requires Replayer 1.1 (or greater) because of compatibility considerations discussed previously.

  1. If you have made any changes to .config files (e.g., bin\Web.config and bin\NLog.config) in the Replayer install directory (e.g., C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics Replayer), then you will need to save those files off to the side during the uninstall/reinstall process.
  2. Open the Programs and Features control panel, find PreEmptive Analytics Replayer, and uninstall it.
    • If the uninstall process warns you that a restart will be required, you must manually restart the host after the uninstall finishes.
  3. After uninstalling and, if necessary, rebooting, copy PreEmptive.Analytics.Standalone.Replayer.exe to the host machine.
  4. As an administrator, run that executable and follow the prompts.
  5. Copy or reapply your configuration changes to the newly-installed configuration files as needed.


Standalone Repository Version 1.1.0. Copyright © 2015 PreEmptive Solutions, LLC