README

=================
ERM Installation
=================

This document describes the installation of Evectors ERM on a Mac OS X system.
Installation under other kinds of Unix systems should defer in small ways only.

Prerequisites
-------------

System
Version:	Mac OS X 10.6

Apache [built-in]
Version:	Apache/2.2

Python [built-in]
Version: 2.6


+ GCC

Version:	4.2

Site:		http://gcc.gnu.org/

Download:	http://itunes.apple.com/us/app/xcode/id422352214?mt=12

Installation:
GCC is part of XCode, currently at version 4.
XCode is no longer part of the standard MacOS distribution, but can be downloaded from the Mac App store for a nominal fee.


+ mod_wsgi

Version: 3.3

Site: http://code.google.com/p/modwsgi/

Download: http://code.google.com/p/modwsgi/downloads/detail?name=mod_wsgi-macosx106-ap22py26-3.3.so

Installation:
1/ copy the downloaded file to /usr/libexec/apache2 and rename it mod_wsgi.so
2/ update /etc/apache2/httpd.conf and add the following line in the LoadModule section:
LoadModule wsgi_module     libexec/apache2/mod_wsgi.so
3/ restart Web Sharing from the Sharing system preferences


+ MySQL

Version: 5.x

Site: http://www.mysql.com/

Download: http://www.mysql.com/downloads/mysql/
Select the Mac OS X ver. 10.6 (x86, 64-bit), DMG Archive

Installation: http://dev.mysql.com/doc/refman/5.5/en/macosx-installation.html


+ MySQLdb

Version: 1.2.3

Site: http://sourceforge.net/projects/mysql-python/

Download: http://sourceforge.net/projects/mysql-python/files/mysql-python/1.2.3/MySQL-python-1.2.3.tar.gz/download

Installation:
$ tar xzf MySQL-python-1.2.3.tar.gz
$ cd MySQL-python-1.2.3
$ python setup.py clean
$ python setup.py build
$ sudo python setup.py install # or su first

The above can of course be done all in one step if you have installed Python's devtools package which includes easy_install:
$ sudo python -m easy_install MySQL-python


+ Django

Version: 1.2.5

Site: http://www.djangoproject.com/

Download: http://www.djangoproject.com/download/1.2.5/tarball/

Installation:
$ tar xzf Django-1.2.5.tar.gz
$ cd Django-1.2.5
$ sudo python setup.py install # or su first

Verification:
$ python
>>> import django
>>> print django.get_version()


+ python-cjson

Version: 1.0.5

Site: http://pypi.python.org/pypi/python-cjson

Download: http://pypi.python.org/packages/source/p/python-cjson/python-cjson-1.0.5.tar.gz#md5=4d55b66ecdf0300313af9d030d9644a3

Installation:
$ tar xzf python-cjson-1.0.5.tar.gz
$ cd python-cjson-1.0.5

Before running setup.py, you need to open it in a text editor and add the following 2 lines:

import os
os.environ['ARCHFLAGS']='-arch i386 -arch x86_64'

Then save the updated version and execute it:
$ sudo python setup.py install # or su first

Note:
Python tends to instal modules with the same options it was compiled with. The python 2.6 version bundled with OS 10.6 is a 'universal binary' with a PPC branch. However Xcode versions after 3.2.6 no longer support the powerpc architecture.


Building and installing
-----------------------

+ Create a new 'document root' folder on your system.

This folder must be named 'erm'. Its content must be read accessible to user '_www'. Copy the content of ERM's git distribution to this 'erm' folder.

+ Update your Apache httpd.conf with a new virtual host for the erm.

You may want to create a specific erm.conf file in /etc/apache2/other.
All conf files in 'other' are included in the Apache configuration.
Copy and paste the virtual host declaration below, then update as needed.

<VirtualHost *:80>

	# if you are testing on your local Mac, check its all lowercase computer name in the Sharing system preferences
	ServerName erm.your_lc_computer_name.local

    ServerAdmin webmaster@localhost

	# your documents root may be anywhere user _www has read access
	# however, the top directory containing the downloaded erm code must be named 'erm'
	DocumentRoot "/Whatever/path/you/please/erm"

	<Directory />
		Options FollowSymLinks
		AllowOverride None
		Order allow,deny
		Allow from all
	</Directory>

	# Update document_root_path in the line below
	WSGIScriptAlias / "/document_root_path/apache/django.wsgi"

	# Update document_root_path in the line below
	Alias /media "/document_root_path/media"

	<Location "/media">
    		SetHandler None
	</Location>

	# Update document_root_path in the line below
	Alias /api "/document_root_path/api"

	<Location "/api">
    		SetHandler None
	</Location>

	# Set up error and access log files as you best please.
	# Remember user _www must have write access to them.
	LogLevel warn

	CustomLog "/Whatever/path/you/please/for/logs/access_log" "%h %l %u %t %T \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""
	ErrorLog "/Whatever/path/you/please/for/logs/error_log"
</VirtualHost>

+ Create a symbolic link for the media directory in the document root:

$ cd /document_root_path
$ ln -s /Library/Python/2.6/site-packages/django/contrib/admin/media media

+ Create an apache folder in your document root and a django.wsgi document in it

$ cd /document_root_path
$ mkdir apache
$ cd apache
$ touch django.wsgi

+ Update your django.wsgi file.

Copy and paste the lines below, updating the path to your document root's parent folder accordingly:

import os
import sys
os.environ['DJANGO_SETTINGS_MODULE'] = 'erm.settings'
sys.path.append('/document_root_path_parent/')
import django.core.handlers.wsgi
application = django.core.handlers.wsgi.WSGIHandler()

+ Create the logging directory.

All erm activity is logged by default in the /var/log/pages folder. To create it on your local machine:

$ sudo mkdir /var/log/pages
$ sudo chown _www /var/log/pages
$ sudo chgrp _www /var/log/pages

If you elect to provide an alternate path, you need to update the settings.py file accordingly, then bounce the apache server processes.

$ sudo apachectl restart

+ Create the erm databases in MySQL.

Run the mysql client and enter the commands listed below. Replace 'password' with any string of your choosing.

$ sudo mysql
mysql> create database erm_db character set utf8 collate utf8_general_ci;
mysql> grant all on erm_db.* to 'erm_user'@'localhost' identified by 'password';
mysql> create database erm_dm_simpledb character set utf8 collate utf8_general_ci;
mysql> grant all on erm_dm_simpledb.* to 'erm_user'@'localhost' identified by 'password';
mysql> flush privileges;

+ Create the local_settings.py file.
Copy and rename the local_settings.py.sample file provided in the distribution:

$ cd /document_root_path
$ cp local_settings.py.sample local_settings.py

Edit it to update the DATABASE_PASSWORD parameter according to your choice at the previous step.

+ Create the Django initial structure.

$ cd /document_root_path
$ python ./manage.py syncdb

When prompted, create a new django superuser and password.


Testing
-------

You should be able to log in as a Django admin at http://your.domain.name/admin.

You should also be able to access the ERM API Explorer at http://your.domain.name/api/explorer/.

This is a good point to start playing with the API, and provides links to all the relevant documentation.

Links to the documentation can also be found in the project's Wiki page on github: https://github.com/evectors/Evectors-ERM/wiki.


Notes
-----

Because MySQL and Python distributions are not fully standardized under MacOS X, installation of Evectors ERM is far from an exact science. If your system version differs from the one described in this document, or run into unexpected errors, refer to the FAQ section of the project's Wiki on GitHub: https://github.com/evectors/Evectors-ERM/wiki.

The ERM code does not include any authentication or encryption layer. All data stored as entities and relationships travels in the clear, and may be updated by anyone with knowledge of the API.

For experimentation, this code base is supposed to execute within your local system, or inside a virtual machine with no direct exposure to the world Wild Web.

When Evectors deploys ERM, its API is always accessed within its server itself, or from systems within a DMZ. The API is never exposed to the Web directly.

To identify each ERM instance, a secret key is part of the API path. You can generate a new pseudo-random key for your installation by running the erm/api/genkey.py script. You then need to copy the key as displayed and paste it in 2 locations:

erm/local_settings.py: update SECRET_KEY
erm/api/explorer/scripts/local.js:
Update the 'key' property of the 'request' object.