Upgrading Urchin 5

Overview

Upgrading Urchin 5 is a straightforward process. The installers typically deal automatically with upgrading existing installations while leaving your configuration and report data intact. This document contains upgrade sections that cover all supported platforms. Please make sure to verify that you are following the appropriate instructions for your situation.

Before performing any upgrades please make sure you do the following:

Back up your entire existing Urchin installation, in particular any customized configuration files.
Shutdown the Urchin services. Having the services disabled will guarantee that there is no database activity while the backup is in progress.
Have a record of the existing installation location and port number of the webserver.

Considerations When Upgrading

It is always advisable to install on your website the latest __utm.js provided with the current release when upgrading Urchin. In addition, as of Urchin 5.7 there is a new UTM, and all users of Urchin 5.x products are encouraged to upgrade to this UTM version even if you do not upgrade to 5.7 at this time.
Campaign Tracking Module users who download Google CPC data must modify their Google download process when upgrading to Urchin 5.6 or 5.7. Please see the help article on importing Google cost data in the Campaign Tracking Module section.
Visitor tracking with UTM-1, UTM-2, or UTM-3: Urchin 5.6 and newer versions are backwards compatible when processing all older versions of UTM data. Although not required, it is strongly advised that you upgrade your website to UTM-4 or later regardless of the Urchin 5 version you are using.
Optimizing UTM-4 settings: UTM-4 improves visitor tracking metrics and options for campaign tracking. If you do not need the campaign tracking capability, you can reduce log space overhead by editing the __utm.js file and setting __utmctm=0. This will still allow you to benefit from the improved UTM-4 visitor tracking.

Procedures

Windows

Doubleclick on the urchin5xxx_win_setup.exe file and follow the instructions in the Welcome and License Agreement dialog screens.
In the dialog screen labeled Preparing to Upgrade Urchin Installation, the installer will present you with a list showing you the directory location and webserver port number it has determined for your existing installation. It will use these parameters for your upgrade. It is not an option to alter the settings of your current installation during your software upgrade, since the upgrade has to match the previous configuration information stored in your Urchin 5 databases.
Click the Next button and the installer will proceed with converting your installation to the new version. Your report and configuration data will automatically be preserved during this process.

UNIX

The install.sh installation script which is bundled as part of all UNIX-type installers will properly upgrade any older version of Urchin 5 installed on UNIX-type systems. When running install.sh, be sure to select Upgrade as the installation type when prompted. Otherwise the upgrade procedure for UNIX is identical to a new installation.

When using install.sh interactively to do an upgrade, at one point you will be presented with the prompt:

Please select the installation type [Default: 1]
   1. New
   2. Upgrade
->

Be sure to select 2 to trigger an Upgrade. If you are using install.sh in non- interactive mode by specifying command line options then be sure to use the -m option to specify an upgrade. Please see the Installation Guide (UNIX) section of the Documentation Center for full instructions on using install.sh.

Mac OS X 10.2.x

Note: Mac OS X 10.1 users should use the section on upgrades for UNIX-type systems.

If you have previously used an Urchin 5 package installer for Mac OS X 10.2, then using a newer package installer will automatically detect your existing Urchin 5 installation and upgrade it. Users in this situation should simply use the instructions in the Installation Guide for Mac OS X 10.2 and skip the rest of the instructions in this subsection as in this case the instructions for new installation and upgrade are the same.

If you did not previously use the package installer, but installed using the install.sh installation script and did not install in the default location of /usr/local/urchin, then you must use a modified procedure to upgrade. The package installer will only install in /usr/local/urchin, so it cannot be used to automatically upgrade another install location. If you have this situation, you have two choices:

Do not use the package installer to upgrade. Instead download and use the same type of installer you used previously. This means you can follow the standard upgrade instructions for UNIX-type systems detailed in the previous subsection.
If you prefer to start using the package installer to upgrade, you can take the steps listed below, but realize that this procedure will cause your Urchin installation to be relocated to the default of /usr/local/urchin:
- Turn off your existing Urchin services using the urchinctl program (i.e. ./urchinctl stop)
- Move the current Urchin installation directory to /usr/local/urchin. You will need to move the entire directory structure starting with the top level directory of your current Urchin installation. For example if you previously had installed Urchin in /applications/urchin, then you would use the following command:
  mv /applications/urchin /usr/local/urchin
  You should verify that you have enough disk space in the /usr/local file system for your current Urchin installation before doing the move.
- Once you've relocated Urchin to the proper location you may launch the Urchin 5 pkg installer and follow the interactive instructions to upgrade

Your old configuration and report data should now be available in your updated Urchin installation.

Sun Cobalt

The Urchin 5 pkg installers for Sun Cobalt systems automatically detect existing installations and upgrade the Urchin 5 files as needed. Simply follow the instructions for a new Sun Cobalt installation to perform an upgrade.