#INSTALLATION

This is a preliminary guide. More advanced examples and recipes will be added here later.

##INSTALL CAKEPHP CODE

Acquire and install the CakePHP framework from http://cakephp.org/ Zuluru is known to work with version 1.3.6 of CakePHP. It will probably work with later 1.3 releases, but will require modifications to run under CakePHP 2.0 and later.

From the command line, you might use something like

$ cd /path/to/cake
$ git init
$ git pull git://github.com/cakephp/cakephp.git 1.3

More instructions for downloading and installing various configurations are at http://book.cakephp.org/view/909/Installation-Preparation and http://book.cakephp.org/view/912/Installation

##INSTALL ZULURU CODE

Acquire and install the Zuluru source code. The CakePHP installation instructions will assume you're putting your application (i.e. Zuluru) in the app folder, but that can cause problems when updating to a newer version of CakePHP. Instead, it is recommended that you put Zuluru in a folder called zuluru, next to the app folder. The remaining directions will assume this is where you've put it. Adjust the steps you take when installing CakePHP for this.

From the comand line, you might use something like

$ cd /path/to/cake
$ mkdir zuluru
$ cd zuluru
$ git init
$ git config remote.origin.url git://github.com/Zuluru/Zuluru.git
$ git pull

##CONFIGURE WEB SERVER

If Zuluru is your primary application (e.g. you have only Zuluru and some HTML files), Zuluru will be at http://www.example.com/. Update your web server configuration to use /path/to/cake/zuluru/webroot as the root.

If you are on a shared webhost, you may not have the level of control required to change the root folder. In this case, see the URLs given in the "INSTALL CAKEPHP" section above for tips on how to proceed.

If Zuluru is co-existing with some kind of content management system, a more common URL would be http://www.example.com/zuluru/. Again, see the URLs in the "INSTALL CAKEPHP" section above for advanced help.

##CONFIGURE ZULURU

As described above, the base URL for Zuluru may vary. Whatever it is (e.g. http://www.example.com/ or http://www.example.com/zuluru), we will refer to that as below. Note that if you do not have mod_rewrite (or equivalent) to provide short URLs, your path may be more like http://www.example.com/zuluru/index.php; in this case, you still follow this with a slash in the URLs you construct below (e.g. http://www.example.com/zuluru/index.php/install).

The following directories under /path/to/cake/zuluru must be writable by the web server at all times (some of these can be modified in the folders section of the config/install.php file):

/tmp
	/cache
		/models
		/persistent
		/views
	/logs
	/sessions
/upload
/webroot/files/temp

The following directories and files under /path/to/cake/zuluru must be writable by the web server during the install process, but can (and perhaps should) be made read-only after installation is complete:

/config
	/core.php

Typically, this can be ensured by setting the owner of the tmp and config trees to the user that the web server runs as. If you get the "An Internal Error Has Occurred" page, it's probably a permissions problem.

At this point, you should (hopefully) be able to point your browser at the Zuluru install, /install. This will ask for information about your database, and some other information about your site. The database must have been created ahead of time, though it can be empty.

Before proceeding with database population, you should take a look at a couple of the files in /path/to/cake/zuluru/config/schema/data. (The installation procedure will remind you of this, and provide the exact paths to these files.) In particular, most installations will want to update the regions file, as this is specific to your geography, and there is no functionality to edit this in the Zuluru interface. Anyone outside North America should update the countries and provinces.

Anything in settings and people can more easily be altered later though the Zuluru interface, so these two should be left alone. The days, event_types and groups files should NOT be altered, as doing so may break functionality.

The install process will create all of Zuluru's database tables and insert default starting information where required, as well as creating the database.php and install.php files in zuluru/config. Once this process is done, you shouldn't need to touch those files, but you can always make changes manually as required.

Once installation is completed and the database has been populated, log in with the administrative user name and password provided, and go through the various pages under the Settings menu to finalize your site configuration.

##CRON SETUP

There are some processes which, if run daily, will help your site run more smoothly. We have found that fetching <ZULURU>/all/cron daily at 1pm works quite nicely. You should be able to set up something to do this for you through the cron mechanism of UNIX/Linux systems, or the Task Scheduler in Windows.

<ZULURU>/all/cron is safe to call multiple times; it remembers what it has done (e.g. emails sent), and doesn't repeat it.

Currently, if you want to see the output from this, you will have to take steps to capture and email it to yourself. Something like this in the crontab file will work:

0 13 * * * root htmlmail admin@zuluru.org "Zuluru daily report" http://demo.zuluru.org/all/cron > /dev/null

Where htmlmail is the following general-purpose script:

#!/usr/bin/php
<?php
$email = $_SERVER['argv'][1];
$subject = $_SERVER['argv'][2];
$url = $_SERVER['argv'][3];

if (function_exists('curl_init')) {
	$curl_handle=curl_init();
	curl_setopt($curl_handle, CURLOPT_URL, $url);
	curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
	curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($curl_handle, CURLOPT_USERAGENT, 'htmlmail');
	$i = 0;
	do {
		$contents = curl_exec($curl_handle);
	} while (empty($contents) && ++$i < 5);
	curl_close($curl_handle);
} else {
	$handle = fopen($url, 'rb');
	$contents = '';
	while (!feof($handle)) {
		$contents .= fread($handle, 8192);
	}
	fclose($handle);
}

$headers = 'Content-Type: text/html; charset="iso-8859-1"';
mail($email, $subject, $contents, $headers, "-f admin@zuluru.org");
?>

##LEAGUERUNNER CONVERSION

If there is demand, the install procedure may be enhanced to detect an existing Leaguerunner database and attempt to convert it to the Zuluru format. Further details will be added here when that work is complete. In the meantime, you can contact admin@zuluru.org for assistance with a manual conversion.

##UPDATES

The source for Zuluru is updated on a regular basis, with bug fixes and new features being added. Most of the time, you will be able to update your local version just by executing $ git pull from your Zuluru folder. If you have made any changes to Zuluru files, this may be more complex, requiring things like "stash", "merge" or "branch". Hopefully, you can use themes and the features_custom and options_custom config files to avoid any such changes.

When updates to Zuluru are released, there may also be changes to the database required. After updating the code, go to <ZULURU>/install/install/update and Zuluru will take care of these changes for you. If you have updated the code but not run this process, Zuluru will prompt you to do so.

##DEBUGGING

If you get blank pages or generic error messages, try changing the debug level in zuluru/config/core.php from 0 to 1 or 2. This should give you details on what's going wrong. Looking at your server's error logs may also provide some help.

##CUSTOMIZATION

You can customize the look of any part of the system using CakePHP's "themes" functionality. See README.themes for more details.

##ADMINISTRATION

For help on setting up fields, leagues, registration events, and the other details required for day-to-day use of the system, see the help in the application.