.. -*- coding: utf-8 -*-

============
Installation
============

:Author: Étienne Loks
:date: 2013-03-16
:Copyright: CC-BY 3.0

This document presents the installation of Chimère.

Prerequisites
*************

If you want to install the Chimère package for Debian Wheezy dependencies are
managed by the package.
You can go to the next section of the documentation.

 - `Python <http://www.python.org/>`_ versions 2.6 or 2.7
 - `Django <http://www.djangoproject.com/>`_ >= version 1.4
 - `South <http://south.aeracode.org/>`_
 - `Postgres <http://www.postgresql.org/>`_ >= version 8.x
 - `Gettext <http://www.gnu.org/software/gettext/>`_
 - `Psycopg2 <http://freshmeat.net/projects/psycopg/>`_
 - `Python Imaging Library <http://www.pythonware.com/products/pil/>`_
 - `Pyexiv2 <http://tilloy.net/dev/pyexiv2/>`_
 - `Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_
 - python-simplejson
 - python-gdal
 - `Lxml <http://lxml.de/>`_
 - `Jquery <http://jquery.com/>`_ version 1.7.1 or better
 - `Jquery-ui <http://jqueryui.com/>`_
 - `Universal Feed Parser <https://code.google.com/p/feedparser/>`_

geodjango is a part of django since version 1.0 but it has some specific
(geographically related) additional dependencies:

 - `geos <http://trac.osgeo.org/geos/>`_ 3.0.x
 - `proj.4 <http://trac.osgeo.org/proj/>`_ 4.4 to 4.6
 - `postgis <http://postgis.refractions.net/>`_ versions 1.2.1 or 1.3.x
 - `gdal <http://www.gdal.org/>`_


Optionaly (but recommanded):

 - `tinymce <http://tinymce.moxiecode.com/>`_
 - `gpsbabel <http://www.gpsbabel.org/>`_
 - django-celery if you want to manage large imports


The simpliest way to obtain these packages is to get them from your favorite
Linux distribution repositories. For instance on Debian Wheezy::

    apt-get install python python-django python-django-south \
        postgresql-9.1 gettext python-psycopg2 python-imaging \
        python-pyexiv2 python-beautifulsoup python-simplejson python-gdal \
        python-lxml libjs-jquery libjs-jquery-ui python-feedparser \
        libgeos-3.3.3 proj-bin postgresql-9.1-postgis gdal-bin \
        tinymce gpsbabel python-django-celery javascript-common 


On Debian Squeeze (you need to activate backports)::

    apt-get install -t squeeze-backports python-django libjs-jquery

    apt-get install python python-django python-django-south \
        postgresql-8.4 gettext python-psycopg2 python-imaging \
        python-pyexiv2 python-beautifulsoup python-simplejson python-gdal \
        python-lxml libjs-jquery libjs-jquery-ui python-feedparser \
        libgeos-3.2.0 proj-bin postgresql-8.4-postgis gdal-bin \
        tinymce gpsbabel javascript-common 

The package *python-django-celery* doesn't exist for Debian Squeeze.

If these packages do not exist in your distribution's repository, please refer
to the applications' websites.

Database configuration
**********************

Now that postgres and postgis are installed, you need to create a new user for
Chimère::

    su postgres
    createuser --echo --adduser --createdb --encrypted --pwprompt chimere-user

Then, you have to create the database and initialize the geographic types (adapt
the paths accordingly to your needs)::

    PG_VERSION=9.1 # 8.4 for debian Squeeze
    createdb --echo --owner chimere-user --encoding UNICODE chimere "My Chimère database"
    createlang plpgsql chimere # only necessary on Debian Squeeze
    psql -d chimere -f /usr/share/postgresql/$PG_VERSION/contrib/postgis-1.5/postgis.sql
    psql -d chimere -f /usr/share/postgresql/$PG_VERSION/contrib/postgis-1.5/spatial_ref_sys.sql

Installing the sources
**********************

.. Note::
   If you are considering to contribute on Chimère get the Git master.

Choose a path to install your Chimère::

    INSTALL_PATH=/var/local/django
    mkdir $INSTALL_PATH

From Debian package
+++++++++++++++++++

If you want to install the last stable version of Chimère
and your system is under Debian Wheezy it is wise to use
Chimère Debian packages.

You can install Chimère this way.

.. code-block:: bash

    # add Chimère repository
    echo "deb http://debian.peacefrogs.net wheezy main" >> /etc/apt/sources.list
    apt-get update
    # install
    apt-get install python-django-chimere

From an archive
+++++++++++++++

The last "stable" version is available in this `directory <http://www.peacefrogs.net/download/chimere/>`_.
Take care of getting the last version in the desired X.Y branch (for instance
the last version for the 1.0 branch is version 1.0.2).::

    wget http://www.peacefrogs.net/download/chimere -q -O -| html2text
    (...)
    [[   ]] chimere-1.0.0.tar.bz2     17-Nov-2010 16:51  53K
    [[   ]] chimere-1.0.1.tar.bz2     17-Nov-2010 16:51  53K
    [[   ]] chimere-1.0.2.tar.bz2     17-Nov-2010 16:51  53K
    (...)

    wget http://www.peacefrogs.net/download/chimere/chimere-1.0.2.tar.bz2

Download, unpack and move the files in an webserser user (www-data for Debian)
readable directory::

    cd $INSTALL_PATH
    tar xvjf chimere-last.tar.bz2
    chown -R myusername:www-data chimere

From the Git repository
+++++++++++++++++++++++

Another solution is to get it from the Git repository::

    CHIMERE_LOCALNAME=mychimere
    CHIMERE_BRANCH=v2.0 # choose v2.0 for stable ou master for bleeding edge
    cd $INSTALL_PATH
    git clone git://www.peacefrogs.net/git/chimere
    cd chimere
    git checkout origin/$CHIMERE_BRANCH


Creating a custom project template
**********************************

A default project can be found on `Gitorious
<https://gitorious.org/chimere-example-project/chimere-example-project>`_. Get
it and start a new project with it (or get another project based on Chimère)::

    cd $INSTALL_PATH/chimere
    git clone git://gitorious.org/chimere-example-project/chimere-example-project.git
    django-admin startproject --template=chimere-example-project mychimere_project
    rm -rf chimere-example-project

Your project name is used for the name of the Python package of your template.
As a Python package it should follow the rule of Python variable name:
it must contain at least one letter and can have a string of numbers, letters and
underscores ("_") to any length. Don't use accentuated letters. Don't begin the
name by "_" because it has special significance in Python.

In your Chimère application directory create *local_settings.py* to fit to your
configuration.
A base template is provided (*local_settings.py.example*) and short descriptions
of the more relevant fields are given below (at least check them). Most of
these settings are initialized in *settings.py*. ::

    cd $INSTALL_PATH/chimere/mychimere_project
    cp local_settings.py.sample local_settings.py
    vim local_settings.py

:Fields:

    * DATABASES: parameters for the database
    * PROJECT_NAME: name of the project
    * SECRET_KEY: a secret key for a particular Django installation. This is
      used to provide cryptographic signing, and should be set to a unique,
      unpredictable value. **Change it!**
    * ROOT_URLCONF: url configuration for your project something like:
      'mychimere_project.urls'
    * EMAIL_HOST: smtp of an email server to send emails
    * TINYMCE_URL: url to tinymce path (default is appropriate for a Debian
      installation with tinymce package installed)
    * JQUERY_JS_URLS: list of jquery and jquery-ui javascript urls (default is
      appropriate for a Debian installation with libjs-jquery libjs-jquery-ui
      packages installed)
    * JQUERY_CSS_URLS: list of jquery and jquery-ui CSS urls (default is
      appropriate for a Debian installation with libjs-jquery libjs-jquery-ui
      packages installed)
    * GPSBABEL: path to gpsbabel  (default is appropriate for a Debian
      installation with gpsbabel package installed)
    * TIME_ZONE: local time zone for this installation
    * LANGUAGE_CODE: language code for this installation

Manage media path permission::

    cd $INSTALL_PATH/chimere/mychimere_project
    chown -R user:www-data media
    chmod -R g+w media

Create log file::

    mkdir /var/log/django
    touch /var/log/django/chimere.log
    chown -R root:www-data /var/log/django/
    chmod -R g+w /var/log/django/

Regroup static files in one path::

    cd $INSTALL_PATH/chimere/mychimere_project
    ./manage.py collectstatic

Compiling languages
*******************

If your language is available in the directory *chimere/locale/*, you will just
need to get it compiled. This can be done with the following command (here,
**fr** stands for French, replace it with the appropriate language code)::

    cd $INSTALL_PATH/chimere/chimere/
    django-admin compilemessages -l fr

If your language is not available, feel free to create the default po file and
to submit it, contributions are well appreciated. Procedure is as follows:

You first need to create the default po file (of course, replace **fr**
according to the language you choose to create)::

    django-admin makemessages -l fr

There should now be a *django.po* file in *locale/fr/LC_MESSAGES*. Complete it
with your translation.

Now that the translation file is completed, just compile it the same way you
would have if the language file was already available.

Database initialisation
***********************

Create the appropriate tables (still being in your Chimère project directory)::

    cd $INSTALL_PATH/chimere/mychimere_project
    ./manage.py syncdb

You will be prompted for the creation of an administrator account
(administration can be found at: http://where_is_chimere/admin/). Then you have
to create tables managed with Django-South::

    ./manage.py migrate

The database is set, congratulations!

You can load the default group permissions (it is at least a good start)::

    ./manage.py loaddata ../chimere/fixtures/auth_group.json

If you want to populate your installation with default data (don't do this on
an already populated instance!)::

    ./manage.py loaddata ../chimere/fixtures/default_data.json

Webserver configuration
***********************

Apache configuration with mod_wsgi
++++++++++++++++++++++++++++++++++

Install *mod_wsgi* for Apache::

    apt-get install apache2 libapache2-mod-wsgi


Create and edit a configuration for Chimère::

    cp $INSTALL_PATH/chimere/apache/django.wsgi \
                   $INSTALL_PATH/chimere/apache/mydjango.wsgi
    vim $INSTALL_PATH/chimere/apache/mydjango.wsgi
    cp $INSTALL_PATH/chimere/apache/apache-wsgi.conf \
                   /etc/apache2/sites-available/chimere
    vim /etc/apache2/sites-available/chimere
    # create log dir
    mkdir /var/log/apache2/chimere/
    chown www-data /var/log/apache2/chimere/

Adapt the files *mydjango.wsgi* (with the correct module) and Apache
*chimere* (with the correct servername and correct paths).

To activate the website, reload apache::

    a2ensite chimere
    /etc/init.d/apache2 reload

If you encounter problem with the upload of files with Unicode chars in their
names, activate the appropriate locale in Apache. On a Debian server with UTF-8
as default encoding, in the file */etc/apache2/envvars* uncomment the following
line::

    . /etc/default/locale


Configuring the Sites framework
*******************************

*Sites* framework allow you to serve the same content on different domains.
Most of you will probably use only one domain but this unique domain has to
be configured. This is done in the web administration interface in *Sites > Sites*.
You only need to change *example.com* by your domain name. If you forget to
do that, some functionalities such as RSS feeds will not work properly.