Urchin 6 Installation Guide (Windows)

• This article authored by EpikOne, an Urchin Software Authorized Consultant

Before You Start - Important Note for Urchin 6.500 Users

Urchin 6.501 fixed several issues in the CPC scheduler. If you are upgrading from Urchin 6.500 to Urchin 6.602, the processed CPC data might be incorrect or incomplete, resulting in incorrect results in the Urchin reports. In order to get correct data from Google Adwords, we recommend that you either (a) install Urchin 6.602 in a new location or (b)if you wish to install on an existing 6.500 instance, delete the old CPC data. In this latter case, delete all contents of the following directories:

<path_to_urchin_6500_installation>\data\cpc\...
<path_to_urchin_6500_installation>\data\history\cpc\...

No action is required if you are upgrading from Urchin 6.600, 6.501 or from Urchin 6.402 and prior.

Overview of Installation Steps

• Install the desired database server on the Urchin system or add Urchin's database to an existing server. The currently supported database engines are:
  • MySQL 5.0.3 or later (Note: Beginning with Urchin 6.6, MySQL 4.x.x is no longer supported)
  • PostgreSQL 8.2.5 or later
• Create the Urchin database and user in on the database server and grant access permissions
• Unpack the Urchin distribution in a temporary folder
• Run the MSI installer
• License the Urchin installation

Option 1: Using existing MySQL database with Urchin

• If you don't already have a MySQL server set up on your system, you can obtain a distribution from http://dev.mysql.com/downloads/. The Windows Essentials package contains all necessary components needed for Urchin usage.

• Install the MySQL server per the instructions on the MySQL site.
• Make sure that you know the MySQL database administrator login (e.g. root) and password.
• Choose the database name, local MySQL user and password you will use with Urchin. Save this information, as you'll need it later during the Urchin installation. The example below creates a database named urchin and a MySQL user name urchin with password urchinpassword (but you should obviously choose your own password!)

• Start the MySQL Command Line Client using Start -> Programs -> MySQL -> MySQL Server -> MySQL Command Line Client.

• In the MySQL Command Line Client window, create the Urchin database, user and permissions with the following commands:

mysql> create database urchin character set utf8;
mysql> GRANT ALL ON urchin.* to 'urchin'@'localhost' IDENTIFIED BY
'urchinpassword';

Option 2: Using existing PostgreSQL database with Urchin

• If you don't already have a PostgreSQL server set up on your system, you can obtain a distribution from http://www.postgresql.org .

• Install the PostgreSQL server per the instructions on the PostgreSQL site.
• Make sure you know the PostgreSQL database administrator login (e.g. postgres) and password.
• Choose the database name, local PostgreSQL user and password you will use with Urchin. Save this information, as you'll need it later during the Urchin installation. The example below creates a database named urchin and a PostgreSQL user name urchin with password urchinpass (but you should obviously choose your own password!)

• Start the PostgreSQL Command Line Client using Start -> Programs -> PostgreSQL 8.2 -> psql to 'postgres'

• In the PostgreSQL Command Line Client window, create the Urchin database, user and permissions with the following commands:

postgres=# CREATE DATABASE urchin WITH ENCODING 'UTF8';
postgres=# CREATE USER urchin WITH PASSWORD 'urchinpass';
postgres=# GRANT ALL ON DATABASE urchin TO urchin;
postgres=# \connect urchin;
postgres=# CREATE LANGUAGE 'PLPGSQL';

Option 3: Using bundled PostgreSQL server with Urchin

• Urchin 6.602 installer comes with bundled PostgreSQL server as an option during Urchin installation.

• In order to use this option Urchin installer should be invoked under user with administrator privileges. Installer will prompt to provide port number and password for the user "postgres". Note: If the user "postgres" already exists in the system, then existing password needs to be provided. If user "postgres" doesn't exist in the system, it will be created with provided password.

• The following limitations apply to the bundled PostgreSQL server:
  • It should not be installed in upgrade mode.
  • Administrator privileges are required for installation.

Installing Urchin

• Unpack the Urchin distribution ZIP archive into a temporary folder.

• If you would like to install a bundled PostgreSQL server, make sure that you don't already have a PostgreSQL server on the system. To install, select the option "Install PostgreSQL" and provide PostgreSQL server details such as the port number and user "postgres" password. Note: Please refer to http://www.postgresql.org if you have any problems installing the bundled PostgreSQL server.

• If you would like to use an existing database, make sure that you have the Urchin database name, user and password for either MySQL or PostgreSQL that you selected above.
• Urchin 6 only allows one instance of Urchin 6 on a single machine (Windows only). If there is an existing version of Urchin installed on the machine, only an upgrade will be permitted. (downgrading is not permitted).
• To perform a 'New' installation, remove any existing version of Urchin 6 from the target machine. To remove Urchin, follow these steps:

  • Start -> Programs -> Urchin 6 -> Disable Urchin Services

  • Start -> Settings -> Control Panel -> Add/Remove Programs

  • Click on "Urchin Software from Google" and choose Remove
  • Once Urchin has been removed, rename the urchin installation folder (e.g. C:\Program Files\Urchin6 folder to Urchin6-OLD).
• Urchin 6.602 can only be used for upgrading certain earlier versions of Urchin 6. The following versions may be upgraded:
  • Urchin 6.6 - Service Pack 1 : Version 6.601
  • Urchin 6.6 - English Release : Version 6.600
  • Urchin 6.5 - Service Pack 2 : Version 6.501
  • Urchin 6.5 : Version 6.500 (See important note above)
  • Urchin 6 - Service Pack 1 : Version 6.402
  • Urchin 6 - International Release : Version 6.401
  • Urchin 6 - English Release : Version 6.400
• For upgrades, stopping/uninstalling the existing Urchin 6 instance is not required. The Urchin 6.602 installer first checks for and uninstalls any existing installation of Urchin 6. Then it installs the Urchin 6.602 files and configurations.
• To begin Urchin 6.602 installation, double-click the urchin6602_windows_installer.msi file and follow the interactive prompts.

• Note: If you had a previous version of Urchin 6 installed and wish to preserve your configuration, be sure that the "Recreate EXISTING Urchin specific database tables (if exist)" option is unchecked. In this case, Urchin will keep the existing configuration intact, but may create 'additional tables' or 'columns in existing tables'.

• You should now have a running version of Urchin on your system. To finish the setup, point your favorite web browser at this URL:

http://yourserver:<port>

where <port> is the network port you chose during the installation (default is 9999).

• If you wish to restore your profile reporting data from an older version of Urchin 6, copy the history and reports folders from C:\Program Files\Urchin6-OLD\data to C:\Program Files\Urchin6
• Click on the Obtain Demo License link and follow the licensing steps to enable Urchin and perform the initial setup steps.

Configuring Tracking

Once Urchin is installed, there may be additional steps required to set up tracking on your website depending on your use case.

Case 1: Using Urchin with IP+User-Agent Tracking

No additional configuration is necessary. When adding profiles to Urchin, be sure to specify IP+User-Agent as the Visitor Tracking Method.

Case 2: Using Urchin with UTM Tracking

To use Urchin with UTM tracking, it is necessary to install a small piece of javascript tracking code on each of your website's pages. Here are the steps:

• Copy the urchin.js and __utm.gif files from the util\utm directory of the Urchin distribution to the document root of your website (e.g. the top level directory of your content)

• On each page of your website, place the following tracking code right after the any META tags in the HEAD section:

<script src="/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
  _userv=0;
  urchinTracker();
</script>

• When adding profiles to Urchin, be sure to specify Urchin Traffic Monitor (UTM) as the Visitor Tracking Method

Case 3: Using Urchin concurrently with Google Analytics

Please note that the new tracking features in the Google Analytics "ga.js" tracking code are not backward compatible with Urchin 6. If you wish to track your website with both Google Analytics and Urchin Software, we recommend using the urchin.js-based tracking code for best results. If you choose to use ga.js, you will not be able to use the new ga.js tracking features.

To use Urchin with a website that is already being tracked with Google Analytics, you just need to make a slight modification to the existing tracking code for Google Analytics. Here are the steps:

• Copy only the __utm.gif file from the util\utm directory of the Urchin distribution to the document root of your website (e.g. the top level directory of your content).

• Add the line _userv=2; as shown below to the existing tracking code on your website pages. Be sure not to modify any other parts of the existing tracking code!

<script src="http://www.google-analytics.com/urchin.js"
type="text/javascript">
<script type="text/javascript">
  _userv=2;
  _uacct="UA-XXXXXXX-Y";
  urchinTracker();
</script>

• When adding profiles to Urchin, be sure to specify Urchin Traffic Monitor (UTM) as the Visitor Tracking Method

Additional Installation Steps for Windows Vista and Server 2008

In addition to the already supported version of Windows (2000, XP and Server 2003), Urchin 6.6+ also supports Windows Vista and Server 2008. Certain security features in these newer Windows versions can affect Urchin execution. Explanation follows below.

UAC - Issue

Windows 2008 contains a new security feature called User Access Control (UAC); for details, please refer to http://technet.microsoft.com/en-us/library/cc709691.aspx.

The known issues when UAC is enabled are:

1. . If UAC is enabled, the application can’t correctly write to the “Program files” folder. Find more details here: http://msdn.microsoft.com/en-us/library/aa905330.aspx

2. . Urchin’s executables can’t be run from a command prompt by default. You must either use the command prompt as administrator or set the properties of the executable as follows: Right click and select Properties-> Compatibility -> “Run this program as administrator” -> OK. Please note that Urchin Windows services operate as expected without any additional effort required.

UAC - Solution

1. Disable UAC and set up Urchin wherever you want. Run Urchin using the binaries or Windows services.
2. IF UAC is enabled, DO NOT install Urchin in the Program files folder. Install it in, for example, your Users directory. Modify the properties to run binaries in admin mode (as described in 2, above) or use Windows services without any changes.