INSTALL

####################
First Installation

Virtualenv is providing a stable environment for Django. (1)

Assuming that svn/git/mercurial, xulrunner (or firefox) and 
Python 2.5+ is already installed it should be enough to follow 
these steps (some commands are specific to Ubuntu with Bash):

1. Clone FlightDeck from github
   $ sudo apt-get install git-core
   $ cd /path/to/projects/
   # If cloning for development please first refer to 
   # https://wiki.mozilla.org/Labs/Jetpack/FlightDeck/Contribution#How_to_start
   # Please your repository in edit mode
   $ git clone git@github.com:{your_username}/FlightDeck.git
   # or if only viewing
   $ git clone git://github.com/zalun/FlightDeck.git

2. Initiate configuration files
   $ cd /path/to/projects/FlightDeck
   $ ./scripts/initiate.sh
   # edit ./scripts/config_local.sh file so it suits your system
   $ vi ./scripts/config_local.sh

3. Install python-setuptools python-dev build-essential libmysqlclient-dev graphviz wget
   $ sudo apt-get install subversion mercurial python-setuptools python-dev build-essential libmysqlclient-dev wget
   # install graphviz (optional)
   $ sudo apt-get install graphviz graphviz-dev

4. Install Pip and VirtualEnv
   $ sudo easy_install -U pip
   $ sudo pip install -U virtualenv

5. Create directory for Python environments
   # current directory: /path/to/projects/FlightDeck
   $ virtualenv --no-site-packages flightdeckenv

6. Install via pip from requirements.txt and custom packages
   $ ./scripts/install.sh 
   # change upload directory preferences so it will be writable by webserver

7. Check if everything is working
   * activate flightdeck environment
     $ source flightdeckenv/bin/activate
     the PS1 may change (regarding on the settings) to
     (flightdeckenv)username@localhost $
   * display the Django version
     $ django-admin.py --version
     # shouldn't be lower than 1.2
   * display list of packages
     $ yolk -l
     Django          - 1.1.1        - active 
     Python          - 2.6.4        - active development (/usr/lib/python2.6/lib-dynload)
     pip             - 0.6.2        - active 
     setuptools      - 0.6c11       - active 
     wsgiref         - 0.1.2        - active development (/usr/lib/python2.6)
     yolk            - 0.4.1        - active 
   * Check if contains everything from requirements file in the right version plus 
     Python, pip and setuptools
     $ cat /path/to/projects/FlightDeck/tools/pip-requirements.txt
     Django
     wsgiref
     yolk

8. Configure the Django application
   $ vi flightdeck/settings_local.py # **

9. Initiate database
   $ ./scripts/syncdb.sh
   # Choose your superadmin username and password
   # You may want to install test fixtures to save time
   $ ./scripts/manage.sh loaddata test_users.json test_basic_usecase.json

10. Test FlightDeck applications
	$ ./scripts/test.sh base person amo jetpack api
   
11. Run Server
   $ ./scripts/runserver.sh
   FlightDeck may be accessed by loading http://localhost:8090/
   Administration from http://localhost:8090/admin/



##############################
Extending the Python codebase

1. Install the package (example of installing PIL - graphics operations for Python)
   $ cd /path/to/projects/FlightDeck
   $ pip install -E flightdeckenv/ pil

2. Save the requirements
   $ pip freeze -E flightdeckenv/ > tools/pip-requirements.txt



##############################
Adding third party projects

1. Install using subversion/git/mercurial if module configured as an egg (2)
   # South is used as an example however we will use pip to install this module
   # Change requirements 
   # add following line to FlightDeck/tools/pip-requirements.txt
   # add line
     -e hg+http://bitbucket.org/andrewgodwin/south/@0.6.2#egg=south
   # update environment 
   $ cd /path/to/projects/FlightDeck
   $ sudo pip install -E flightdeckenv/ -r tools/pip-requirements.txt
   
2. Install custom packages
   # Add to the scripts/install.sh
   # checkout the right revisions into $SRC
   sudo svn checkout http://django-grappelli.googlecode.com/svn/trunk/grappelli/ $SRC/grappelli
   # Link module from #SRC to to $SITE_PACKAGES
   if [ ! -e $SITE_PACKAGES/grappelli ] 
   then
       $ sudo ln -fs $SRC/grappelli $SITE_PACKAGES/grappelli
   fi

###################
Configuring Apache

1. Edit WSGI script
   * /path/to/projects/FlightDeck/apache/config_local.wsgi
   * replace /path/to/projects to real path

2. Edit Apache config (Ubuntu way)
   # copy config file
   $ sudo cp /path/to/projects/FlightDeck/tools/apache-example.conf /etc/apache2/sites-available/flightdeck
   # edit and change paths in /etc/apache2/sites-available
   # enable site
   $ sudo a2ensite flightdeck
   $ sudo /etc/init.d/apache2 reload
   # change permissions to database file (if using sqlite3)
   $ sudo chown :www-data ../FlightDeck dev.db
   $ chmod g+w ../FlightDeck dev.db
   # browse http://flightdeck.localhost

3. Database
   # If using sqlite3 please make the project directory writable by Apache as well as the 
   # database
   $ sudo chgrp www-data /path/to/projects/FlightDeck
   $ sudo chgrp www-data /path/to/projects/FlightDeck/dev.db
   $ sudo chmod g+w /path/to/projects/FlightDeck
   $ sudo chmod g+w /path/to/projects/FlightDeck/dev.db


#####################
Updating environment

1. Install from pip-requirements.txt
   $ cd /srv/python-environments
   $ sudo pip install -E flightdeck/ -r /path/to/projects/FlightDeck/tools/pip-requirements.txt


----

**  No *_local.py file should be shared between users, they contain
    informations relevant only to the local installation of FlightDeck.
    The exclude file is provided by default.

----
(1) Installation of VirtualEnv under Ubuntu is described in detail in this post: 
    http://www.saltycrane.com/blog/2009/05/notes-using-pip-and-virtualenv-django/

(2) Pip requirements file format
    http://pip.openplans.org/requirement-format.html