Preparing for an upgrade

Before you start the upgrade, prepare your OpenX environment:

• Backup your system
• Prepare the database
• Download OpenX
• Copy OpenX to your server
• Configuration file locator
• Next step: Upgrade wizard

Backup your system

Important: Backup your OpenX directory and your database before starting the upgrade.

Prepare the database

The upgrade process guides you through synchronizing your old and new databases. However, there can be additional preparations:

• Lowercase table prefixes: if your existing database contains prefixes that use capital letters, you must change all prefixes to lower case before you perform the upgrade.
• Large database: during the upgrade OpenX copies each affected table, which can be very time-consuming for large databases. To avoid this process, create a file named "NOBACKUPS" in the var/ directory for your new version of OpenX. When the Install Wizard detects this file it does not copy tables.

Note: This procedure is described in Step 3 of the 'Copy OpenX to your server' section.

Download OpenX

Download the latest version of OpenX from the OpenX website to your local computer.

Copy OpenX to your server

To copy OpenX to your server:

• Create a new directory with the same directory name as your previous installation, but add the newfiles suffix to the end of the directory name. For example: directoryname_newfiles.
• Unpack the latest release of OpenX into this new directory.
• Copy the configuration file from the current working location to the
  directoryname_newfiles/var directory of the new version.
  Note: The Configuration file locator provides the location of the configuration file in all versions you can upgrade from.
• Copy your banner images from currentdirectory/www/images to directoryname_newfiles/www/images

More information: The banner images could be stored in a different location if you changed your banner settings. To check the location you have set for images, search for the webDir parameter in the configuration file.

• If you have a large database and do not want to wait while OpenX copies all database tables affected by the upgrade, create a file named "NOBACKUPS" in the var directory such as directoryname/var/NOBACKUPS.
• Add the _backup suffix to the end of the name of your existing working directory, to rename it as directoryname_backup.
• Rename directoryname_newfiles by removing the newfiles suffix.

The following table shows where to find the configuration file in OpenX:

Configuration file locator

Buckets

• OpenX 2.8 introduces a completely new logging technique using tables called 'buckets' You can view example tables here. This new logging method replaces the old raw data-based logging used in OpenX 2.4 and OpenX 2.6 (and which was optional in phpAdsNew/Openads 2.0).
• To ensure your statistics are not lost during an upgrade to OpenX 2.8, the code base handles the process of converting your old raw-format logged data into bucket-based data. However, this process is NOT part of the upgrade wizard as it may take some time to perform. Instead, the upgrade wizard will set a flag in your database, which will instruct the OpenX 2.8 maintenance script to perform the conversion for you when it next runs. This means that it is vital that you disable the crontab that calls your old OpenX 2.4 or OpenX 2.6 maintenance script before you upgrade, and make sure that when you have finished the upgrade, you set the OpenX 2.8 maintenance script to run (see the Running maintenance page).
• If you do not use crontab to run maintenance (see here), it is recommended that you disable auto-maintenance before you upgrade, and then run the maintenance script manually after upgrading. Once the manual run of maintenance is completed, you can then re-enable auto-maintenance. (If it is impossible to run maintenance manually on your server, then simply re-enable auto-maintenance after the upgrade. This will work, but is not the preferred method.)
• If you would like to check to ensure that your old raw data has been correctly migrated, simply check your debug.log file for output along the lines of the example located at the bottom of this section. If you do not see this in your debug.log file, check your debug logging settings - perhaps you have configured OpenX to use a differently named file, or changed the output level of debugging? (Read more about debug settings here.)
• If you are running OpenX with the Distributed Statistics mode, you need to ensure that all raw data and all buckets are migrated to the central database server before running the OpenX 2.8 central maintenance script. The recommended approach is:
  
  • Before starting the upgrade, disable the running of the central and distributed maintenance scripts on ALL servers.
  • Perform the upgrade.
  • On all delivery servers, run the old OpenX 2.4 or OpenX 2.6 distributed maintenance script. Check the log files to ensure the raw data has been transferred correctly to the central database.
  • On all delivery servers, set up the crontab running of the new OpenX 2.8 distributed maintenance script. Check the log files to ensure the bucket data has been transferred correctly to the central database.
  • On the central server, set up the crontab running of the new OpenX 2.8 central maintenance script.
• Finally, because the old OpenX 2.4 and OpenX 2.6 raw data tables can sometimes be very large, and contain different data to the new bucket tables, OpenX 2.8 does NOT delete any data from the old format raw tables. If you would like to reduce your OpenX database size after upgrading to OpenX 2.8, we recommend that you allow OpenX to run for a suitable length of time to ensure that everything is okay, and then manually prune your raw data tables.

Maintenance debug.log output when migrating old style raw data:

Jan 12 14:32:08 +0000 OA [ info] - The OpenX maintenance process has detected that it is running immediately after Jan 12 14:32:08 +0000 OA [ info] an upgrade from OpenX with version less than 2.8. As a result, there may be old Jan 12 14:32:08 +0000 OA [ info] format raw data logged that needs to be processed. This data will now be processed...
+ additional debugging information, if output level set to PEAR_LOG_DEBUG.

Next step: Upgrade wizard

When you are satisfied that you have fully prepared the system, open a web browser and visit your OpenX website to start the upgrade wizard.