INSTALL

# Install instructions #

Here be the way of getting zookeepr going.

## HTML output ##

This file is formatted with
[Markdown](http://daringfireball.net/projects/markdown/). You can get nicely
formatted HTML output with the following commands.

		aptitude install markdown # install somehow Markdown
		markdown INSTALL > /somewhere/install.html

Open this file with your preferred browser. For example Epiphany.

		epiphany /somewhere/install.html &

## Installing the Dependencies ##

In these instructions `the-development-directory` is the directory containing this INSTALL file.

Regardless of what method you use to install the dependencies,
if the result doesn't work check the dependencies listed in
setup.py against what you have installed.

### Installing without using a distro's package management ###

This requires Python >=2.6 and virtualenv.  Install latest pylons in a development directory: 

		cd the-development-directory
		virtualenv pylons
		alias pylons="source `pwd`/pylons/bin/activate"
		pylons
		python setup.py develop
		
		(when using paster you may require using ./pylons/bin/paster)

### Installing using Debian style package management ###

These instructions have been tested on:

  - Ubuntu Lucid 10.04 LTS
  - Debian Squeeze
  - Debian Lenny

Some Lenny packages are too old.  So on Lenny only, install them from backports:

  - Add debian-backports to /etc/apt/sources.lst
		sudo vim /etc/apt/sources.list

		# add a line like:
		deb http://www.backports.org/debian lenny-backports main contrib non-free

		# save the file and exit, then
		sudo apt-get update

		aptitude -t lenny-backports install bzr debian-backports-keyring python-pylons

On all Debian derived distributions, do the following:

		aptitude install python-authkit python-dnspython python-imaging python-pip \
			python-pastedeploy python-pylons python-setuptools python-vobject pwgen
		cd the-development-directory
		sudo pip install pytz

On Debian wheezy and up:
		sudo aptitude install python-libravatar

otherwise:
		sudo pip install libravatar

		Note: on Lenny only it was found that the version of AuthKit supplied in package python-authkit
		did not work with zookeepr dependencies.  If you see a stacktrace in authkit with the line
		digest0 = md5.new -- built_in_function_or_method object has no attribute 'new' then the 
		following fix may cure the issue by installing updated packages and dependencies in /usr/lib/site-python:

		sudo easy_install --upgrade AuthKit>=0.4.3

		This is not needed on unstable (Ubuntu Lucid)

### Installing using RPM style package management ###

These instructions have been tested on:

  - Fedora 14

Do the following:

	sudo yum install python-pylons pwgen pytz python-vobject python-dns python-sqlalchemy
	sudo easy_install pylibravatar AuthKit
	git clone https://github.com/zookeepr/zookeepr.git
	cd zookeepr

### PDF generation ###

You need to install the following package for PDF generation to work, e. g.:

		aptitude install inkscape

		Note: This will pull in a base X11 install with client libraries, as well as GTK+
		and cairo. It will not install the X server.

### Keysigning code ###

To allow the generation of key fingerprint pages you will need to install the
following packages:

		aptitude install gnupg mpage ghostscript

### UML Graph code ###

You can generate a UML graph of all the models by installing dot. This
is commonly found in the graphviz package

		aptitude install graphviz

Found at /uml_graph.png (or .svg, .jpeg etc).

## Installing and setting up Zookeepr ##

 - Set up the Pylons environment:

	alias pylons="export PYTHONPATH=$PWD/setup-dir"
	mkdir $PYTHONPATH
	pylons
	python setup.py develop --no-deps --install-dir=$PYTHONPATH
	cd zookeepr

### Set up the development environment ###

 - Set up the environment:

		cd the-development-directory
		pylons			# command created by the alias above

 - Copy sample `lca_info.py` in place, edit it to turn on registrations, CFP etc.

		cp zookeepr/config/lca_info.py.sample zookeepr/config/lca_info.py

 - Create a `config.ini`.

		paster make-config zookeepr config.ini

If the make-config step complains that a package version - e.g. SQLAlchemy -
is incorrect, and you change setup.py to make it work, you have to run the
setup.py develop step again (see the Installing and setting up Zookeepr
section).

 - The default `config.ini` uses sqlite, which is fine for development.  To use a different SQL backend edit `dburi`.

 - Generate an empty database:

		paster setup-app config.ini

 - To easily regenerate the database during development check out:

		bin/reset-development-db
 
## Running Zookeepr ##

 - Set up the environment:

		cd the-development-directory
		pylons			# command created by the alias above

 - Run ZooKeepr:

		paster serve --reload -v config.ini

## Administering Zookeepr ##

 - A default admin account exists with the following credentials:

   email:    `admin@zookeepr.org`  
   password: `password`

 - By visiting <http://127.0.0.1:5000/admin> you will be prompted to log in and
   redirected to the administration hub.

 - Be sure to update/delete this user before deploying!

## Deploying Zookeepr as a web app ##

### Apache ###

 - /etc/apache2/sites-enabled should look like
	
	<VirtualHost *:80>
	    DocumentRoot /path/to/zookeepr/checkout
	
	    # Configure the cluster member proxy
	    <IfModule mod_proxy.c>
	        ProxyRequests Off
	        <Proxy *>
	            AddDefaultCharset off
	            Order deny,allow
	            Allow from all
	        </Proxy>
	        ProxyVia On
	    </IfModule>
	
	    <Proxy balancer://zookeepr>
	        BalancerMember http://127.0.0.1:5000
	    </Proxy>
	
	    RewriteEngine On
	
	    # If there is a maintenence.html file in your
	    # public dir all requests will get rerouted to
	    # this file.
	    RewriteCond %{DOCUMENT_ROOT}/maintenance.html -f
	    RewriteCond %{SCRIPT_FILENAME} ^/public/.*
	    RewriteRule ^(.*)$ $1 [L]
	
	    RewriteCond %{DOCUMENT_ROOT}/maintenance.html -f
	    RewriteCond %{SCRIPT_FILENAME} !maintenance.html
	    RewriteRule ^.*$ /maintenance.html [L]
	
	    RewriteCond %{DOCUMENT_ROOT}/public/%{SCRIPT_FILENAME}  -f
	    RewriteRule ^(.*)$ /public/$1 [L]
	
	    # All dynamic requests get sent to the cluster
	    RewriteRule ^/(.*)$ balancer://zookeepr%{REQUEST_URI} [P,QSA,L]
	    ProxyPassReverse / http://127.0.0.1:5000/
	
	  <Directory "/var/www-sites/www.lca2010.org.nz/html">
	    Order allow,deny
	    Allow from all
	  </Directory>
	
	</VirtualHost>

    - In the HTTPS VirtualHost add
    RequestHeader set X_FORWARDED_PROTO "https"