How to: Upgrade OpenX Ad Server

A few years ago, I published an article on this blog, describing the procedure I was using at the time for upgrading an existing OpenX installation. Over time, I’ve made small changes to this process based on experience. The article below describes how I currently do these upgrades.

Notes and disclaimer

Before I start, the most important tip I can give is: make backups!

Another important note: the procedure below is based on my personal experience upgrading several hundred OpenX installations over the last few months. I’ve generalized the process so that it can be applied in many situations. However, I don’t claim that this process will work in all cases and for all people.

Starting point

Single server setup

The procedure described below is for a setup where there is just one server that handles everything related to OpenX. When you have a setup with multiple servers, the basics of the upgrade process are the same, but obviously you’ll need to make some changes to the various steps. If you’ve managed to get a setup with multiple servers running, then I’m sure you’ll understand the differences.

OpenX installed in www.example.com/openx/

I’m starting with the assumption that you’ve installed your OpenX system on your website example.com in a folder called ‘openx’ (so the address is www.example.com/openx/), and that it has been installed and configured correctly.

OpenX running on a dedicated database

I’m also assuming that you are using a database called “openx_xyz”, where xyz is the version number of your current OpenX version. So if you’re running OpenX v2.8.4, your database would be named “openx_284″.

I’m also assuming that you have a specific MySQL user for the OpenX database, and that this user has “all privileges” on that database. For the examples below, I’m going to assume that this user is called “openx”.

Banner images stored in www.example.com/images/

I’m also assuming you have moved your banner image storage folder to a location outside of the OpenX directory. If you haven’t done that yet, then I suggest that you first do this by following the instructions in the earlier blog post How to: move banner image storage location in OpenX.

Overview of steps in OpenX upgrade process

The upgrade process consists of two major parts: preparations and upgrade.

The preparations involve:

  1. Uploading the files of the new software version in a new folder on the server
  2. Creating a new database
  3. Copying and adjusting the configuration file
  4. Preventing the creating of backup tables
  5. Setting file and folder permissions

The actual upgrade involves:

  1. Copying the database
  2. Running the upgrade wizard
  3. Making the upgraded copy the live system

Read this procedure carefully and completely

I strongly recommend that you read this whole procedure carefully and completely before starting. That way, you will know what to expect and what tools and information you will need.

You might even want to consider to do a dry run of the upgrade on a staging server or test copy of your system.

Preparations for upgrading OpenX

1. Upload the files of the new software version

The OpenX software has been designed so that it can run the upgrade wizard in a temporary folder. This means that the current software version will not be touched or changed in any way during the upgrade process. In the unlikely event that something goes wrong while running the upgrade wizard, the ad delivery on your site(s) will not be affected.

My first step in the preparations is to create a new folder at the same level as the existing ‘openx’ folder. I always call this folder ‘openx_new’. Then I use my FTP program to upload the files of the new version into the new folder. I always unpack the zip file I download from OpenX.org on my own computer first and then I upload the resulting file set to the web server.

2. Creating a new database

Instead of running the upgrade on the existing database, I always run the upgrade wizard on a new copy of that database. That way, when anything goes wrong during the upgrade, the original database will be unharmed and will continue to work as if nothing happened.

The second step is the preparations is to create a new database with a name that reflects the new version number. For example, if you’re upgrading to OpenX version 2.8.7, your new database might be named “openx_287″.  Create this new database, and also make sure that the MySQL user “openx” has “all privileges” on the new database.

3. Copying and adjusting the configuration file

The upgrade process described here means you’ll be running the upgrade wizard with the new database created in the previous step. To make this work, you will have to adjust the OpenX configuration file for the upgrade folder to point to the new database.

The OpenX configuration file can be found in the ‘var’ folder just below the ‘openx’ folder. The name of the starts with your domain name and ends in ‘conf.php’. So for our fictional installation at www.example.com/openx, the configuration file is named www.example.com.conf.php.

First download it to your local computer using your FTP program, and open it in a text editor like Notepad. You’ll need to make one change to the configuration file. Search for the database name in the [database] section, and change it to the name of the new database that you have created in the previous step.

Then upload it into the ‘var’ folder just below the ‘openx_new’ folder.

4. Preventing the creating of backup tables

The OpenX upgrade wizard normally creates backup versions of all the tables in your OpenX database that are changed during the upgrade. These backup tables are used to attempt a recovery when the upgrade goes wrong in any way. If you’re database is large, and if the tables that need to be backed up this way are also large, this can result in a very big increase in the overall size of the database. It will also mean the upgrade will take longer than without these backups.

However, since this upgrade scenario involves creating a new database, copying all existing data into this new database and then running the upgrade on that new copy database, there is no real need for the creating of those backup tables.

There is a trick to prevent the creating of the backup tables. Just create a file named “NOBACKUPS” in the ‘var’ folder just below your ‘openx_new’ folder. The file can be completely empty, it’s just the name and the fact that it’s there that tell the upgrade wizard to skip creating backup tables.

5. Setting file and folder permissions

During the upgrade, but also during normal operations, OpenX software requires that several files and folders can be created or changed on the server. This means you will have to change the permissions of those folders and files. The upgrade wizard will check this in one of the first steps, forcing you to make the changes at that time, but it’s easier to do it now during the preparations.

The following folders, plus all files and sub folders in them, will to be set to “world writable”:

  • ‘openx_new/plugins’
  • ‘openx_new/var’
  • openx_new/www/admin/plugins’

If your server is running on Linux or Unix, the permissions have to be set to ‘777’.

Selecting a day and time for the upgrade

It’s a good idea to carefully plan the day and time for the actual upgrade. Most sites will have a distinct day-and-night pattern in their visitor statistics. If you can, perform the upgrade during the least busy time of the day (or night). This has several advantages.

  1. The server will be less busy than during the daytime, and thus faster when it comes to making changes to the database tables and files and folders in OpenX.
  2. It’s likely that nobody will be working in the OpenX user interface during the night, adding campaigns or banners for instance. In any event, tell anyone on your team that uses OpenX to avoid working in OpenX during the upgrade process.
  3. For the time it takes to perform the upgrade, you will miss a few minutes worth of statistics. If you do the upgrade at a time when few visitors are on the site, you’ll miss as little as possible.
  4. At the very end of the upgrade, you’ll have to swap the ‘openx’ and ‘openx_new’ folder names. Depending on how fast you can type, this will take a few seconds. Doing this at a quiet time of the night will mean that hardly anyone will notice it.

Whatever day of the week and time of day you select, make sure that you start the upgrade steps just after the hourly maintenance process is completed. This means you’ll have a consistent copy of your data and that you’ll only be missing a few impressions, clicks and possibly conversions while going through the upgrade process.

It might be that you’ll have to decide to do the upgrade during the night from Sunday to Monday. So the disadvantage is obviously that you’ll have to sacrifice a chunk of time otherwise spent sleeping.

Performing the upgrade

With all preparations complete, it’s time to perform the upgrade for real.

The steps below will have to be performed in the shortest possible time. Make sure you’re not going to be disturbed or distracted by phone calls, meetings or people walking in to have you do other things. The time it will take to complete the whole upgrade largely depends on the size of your database and the speed of the server. It could be as quick as a few dozen seconds, but it might actually take minutes or even half an hour.

1. Copying the database

As explained in detail above, the upgrade process involves making a copy of your production database into a newly created database and then to run the upgrade on this new database.

If you’re not comfortable with command line statements, you might be able to use a tool like phpMyAdmin to copy all of your tables from the existing database ‘openx_abc’ into the new database ‘openx_xyx’.

However, it is often faster to use a few command line statements to export the data from the existing database and then to import it into the new database. If you don’t know how, ask a colleague, team member or outside expert for help.

Here is a template for the command line statements.

To export data from the existing database into a text file:

mysqldump -uUSER -pPASSWORD OLDDATABASE –skip-lock-tables > FILE.sql

To import data from this text file into the new database:

mysql -uUSER -pPASSWORD NEWDATABASE < FILE.sql

You’ll have to replace the USER, PASSWORD, OLDDATABASE and NEWDATABASE placeholders with the actual names and values.

Whatever way of copying the data you use, always make sure that you’ve got a copy of all the tables of your existing database. You can do this by comparing the list of tables of both databases.

2. Run the upgrade wizard

After you’ve completed copying the database as described in the previous step, you can run the upgrade wizard.

In your web browser, enter the address of your new OpenX version, which in the example used in this article would be:

http://www.example.com/openx_new

The OpenX software will recognize that an upgrade is in progress and instead of presenting the usual login screen it will start the upgrade wizard.

The upgrade wizard will do the necessary work for you. It involves a welcome screen, and a check for the technical requirements for your server to be able to successfully use OpenX.

At some point you will have to prove that you are authorized to perform the upgrade by entering the OpenX administrator user name and password. The newest versions of the OpenX software will also ask (or rather force) you to login in on an existing OpenX account or to create a new OpenX account.

The wizard will also display the database connection details that it finds in the configuration file. Check and make sure that you’ve changed the database name in the configuration file to point to the new database containing the copy of the data.

After this check, the upgrade wizard will make all necessary changes to the database tables. Depending on the size of the database and the speed of your server, this could take just a few seconds but it might take several minutes.

After the database changes have been completed, the upgrade wizard will display the folder path of the ‘old’ copy of OpenX. Since we’re actually working in a temporary folder, this should in fact be the folder path of the current, live version of the system. Check and confirm that the path is correct. The upgrade wizard will now find out which plugins are installed in the current version and then install the same set of plugins in the new version. During this step, it will even check if there are any new versions of any of the plugins and if so, it will install those instead of the older versions. Some plugins will actually create or change tables for their own use.

At the very last step of the upgrade wizard, it will present a page informing you that the upgrade was successful. If you click the “OK” button on that page, your browser will be redirected to the ‘official’ address of your OpenX installation, which is http://www.example.com/openx/www/admin/. Since you are not currently logged in on that folder, you’ll be presented with a login screen. Don’t be alarmed! The next step will take care of this.

If something goes wrong while running through the upgrade wizard, carefully read any warnings, errors and notifications you see in the browser. In almost all cases it will be clear enough how the problem can be corrected. You’ll have to decide if you want the correct the problem(s) right away and continue or if you’ll need to postpone the upgrade for more complex problem fixing later.

Whatever is the case, do not perform the next and finals step in the event of any major problems during the upgrade wizard.

3. Swap the folder names to have the upgraded copy delivering ads

If the upgrade wizard completes without errors or problems (see the last paragraphs of the previous step), all that is left is to swap the folders to make your upgraded copy the live copy. Here’s how:

  • Rename your existing ‘openx’ folder to ‘openx_old’
  • Rename your new ‘openx_new’ folder to ‘openx’

This should ideally be done in a short sequence, within a matter of seconds.

Finally…

After going to this complete upgrade procedure, you are now running the new version of the OpenX software in the original folder name www.example.com/openx. So there is no need to make any changes to the invocation code on your site(s).

I would recommend to keep the ‘old’ version of the software, currently sitting in the ‘openx_old’ folder, around for a little while. If you find anything wrong with the new version, you can easily switch back to the old version (including the original database) by changing the folder names back to their original names: openx to openx_new, and then openx_old to openx.

How to: move banner image storage location in OpenX

Share this on:
  • Twitter
  • LinkedIn
  • Facebook
  • email
About Erik Geurts

Comments

  1. Deepak Bhardwaj says:

    Hi Erik Geurts,

    First of all thanks for posting the upgrade procedure over here.

    We have just performed an OpenX upgrade from version 2.8.3 to version 2.8.7. It completed successfully but we are facing a problem with the existing content. The new content is being served by the ad server but the existing content is not.

    We have tried re-building the cache.

    Could you please advise what might have caused this problem?

    Thanks

    Regards,

    Deepak

    • Hi Deepak,

      Thank you very much for your comment.

      What do you mean exactly when you say “the new content is being served () but the existing content is not”? In my view, there is no such thing as new or existing content, when you change the folder name of the upgraded OpenX installation to ‘openx’, the invocation code on the website will start to pull the ads from that new folder.

      Regards, Erik Geurts

  2. Has anyone seen issues with upgrading to 2.87? I recently upgraded and now ads aren’t delivering. Has anyone seen this too?

    • Hi Joseff,

      Thanks for your comment.

      I have seen many reports from people that have upgraded to version 2.8.7 and then saw various problems in their ad serving. The most common problem people report is that their statistics don’t work anymore.

      In almost all cases where this happened, the cause is that the upgrade to OpenX v2.8.7 may have failed to migrate the OpenX plugins from the previous to the new version. I do not know what causes this, frankly. I’ve done a number of upgrades to OpenX v2.8.7 myself, and in all cases the migration of plugins went just fine.

      Have you checked to make sure that the plugins are available in version 2.8.7?

      Regards, Erik Geurts