Installation

padams edited this page May 31, 2016 · 5 revisions

Table of Contents

Before you begin...

  • Read the technical requirements to make sure that OWA can be installed on your system.
  • Read the required permissions page to understand what file system permissions are required by OWA during install as well as how you can harden your instance after installation is complete.

Stand Alone Installation

Pre-Install Steps

Before you start the installation there are a few server environment setups that you'll need to ensure are in place or completed.

File System Permissions

Ensure that OWA's files and directories have the proper file system permissions.

Setup Your Database Connection

As part of the OWA installation process, you will be asked for database connection information that will be used by OWA to create its tables and begin logging statistics. Prior to starting the install process you will want to either setup a new database for OWA to use (recommended) or choose an existing database. Either way OWA's installer requires a few pieces of database connection info:

  • Database Host - this is the name of the host on which the database can be accessed. This could be a remote host such as db.yourdomain.com or, if OWA is running on the same host as your database instance you can use localhost.
  • Database Name - this is the name of the database that OWA should read and write to. This database needs to be created if it does not exist prior to starting the install.
  • Database User - this is the user account that OWA will use to connect to your database. This database user account must have permission to read and write to the database that you want OWA to use.
  • Database Password - this is the password of the database user.
As part of the installation OWA will write this information to a newly created owa-config.php configuration file - where it can be changed later if you need to modify the database that OWA read and writes from.

The OWA installer will create all the tables that it needs using the owa_ table prefix.

Installation Steps

  1. Download the latest OWA distribution or check it out of the Git repository.
  2. Place the 'owa' folder somewhere within the document root of your web server. The 'owa' folder must be accessible by web browsers.
  3. Start the installation wizard by pointing your web browser at: http://yourdomain/path/to/owa/install.php

WordPress Installation

To install OWA under a single instance of Wordpress, follow these steps:

  1. Download the latest OWA distribution or check it out of the Git repository.
  2. Move the entire 'owa' folder into the WordPress plugins folder which is located at /path/to/wordpress/wp-content/plugins. NOTE: the folder must be named 'owa' (without the quotes) to work.
  3. Login into your WordPress blog and activate the plugin via the "Plugins" admin screen. This will create all of the required database tables in the same database that WordPress is using. OWA tables will be created with the owa_ prefix by default.
That's it. OWA will immediately start tracking WordPress generated web pages and feeds. In addition, you can then configure various OWA options in WordPress by visiting the OWA options page which should now appear under the main Options tab in the WordPress admin interface.

Track WordPress site using an existing OWA instance

In order to use the OWA WordPress plugin you must have a full separate OWA instance installed as a plugin under WordPress.

You can however have your OWA WordPress instance write to the same database as your other OWA instance so that statistics for your WordPress site are available through your existing instance of OWA. To do so, follow the same WordPress instructions but create your owa-config.php file manually (using the same database login info as your existing OWA instance) before activating the WordPress plugin. This will ensure that data will be consolidated into the same database.

WordPress Theme Compatibility

In order for OWA's WordPress plugin to work, your WordPress theme needs have the following line of php somewhere above the body tag in its footer.php template:

<?php wp_footer(); ?>

Most WordPress themes are well formed and come with this Wordpress API call in the footer.php template already, so most people will not need to modify their theme to make OWA work. For more information on how to make sure that your themes work with WordPress plugins see: http://codex.wordpress.org/Theme_Development

Incompatible WordPress Plugins

  • WP-Cache - OWA does not currently work if WP-Cache is active. Specifically it breaks tracking and the geolocation reports due to it's instance on a setting text/html Content-Type HTTP header.

MediaWiki Installation

NOTE: The OWA MediaWiki plugin will disable all of mediawiki's content caching features. This is needed to track mediawiki pages at this time.

  1. Download the latest OWA distribution or check it out of the Git repository.
  2. Move the entire OWA folder into MediaWiki's extensions folder.
  3. Add the following line of PHP to the bottom of MediaWiki's LocalSettings.php file:
    require_once('extensions/owa/mw_plugin.php');
  4. Navigate to MediaWiki's list of Special pages
  5. Click on the Open Web Analytics Special page
  6. Follow on-screen instructions to install OWA.

Re-installing OWA

A clean re-install of OWA requires the following:

  • drop all owa_ tables from your database
  • remove the cache directory for your configuration (usually: /path/to/owa/owa-data/caches/1)

Updating an existing OWA Instance

See the updating page for details on how to update your existing OWA instance.