path: root/docs/install.rst

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

====================
Chimère installation
====================

:Author: Étienne Loks
:date: 2012-08-03
:Copyright: CC-BY 3.0

This documents presents the installation of Chimère.
The version has been updated for installation of version 2.0-RC3.

-----------------
Base installation
-----------------

Installation
------------

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

 - `apache <http://www.apache.org/>`_ version 2.x
 - `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/>`_
 - `Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_
 - python-simplejson
 - python-gdal
 - `unidecode <http://pypi.python.org/pypi/Unidecode>_
 - `lxml <http://lxml.de/>`_
 - `jquery <http://jquery.com/>`_ version 1.7.1 or better
 - `jquery-ui <http://jqueryui.com/>`_

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
 - `posgis <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             \
        python-beautifulsoup tinymce apache2 libgeos-3.3.3 proj-bin gdal-bin \
        python-gdal python-lxml python-psycopg2 python-imaging gettext   \
        postgresql-9.1 postgresql-9.1-postgis libjs-jquery libjs-jquery-ui \
        python-django-celery python-simplejson python-gdal gpsbabel

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

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

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


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
chimere::

    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)::

    createdb --echo --owner chimere-user --encoding UNICODE chimere "My Chimère database"
    psql -d chimere -f /usr/share/postgresql/9.1/contrib/postgis-1.5/postgis.sql
    psql -d chimere -f /usr/share/postgresql/9.1/contrib/postgis-1.5/spatial_ref_sys.sql

Install the sources
*******************

Choose a path to install your Chimère::

    INSTALL_PATH=/var/local/django
    sudo mkdir $INSTALL_PATH

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.
Extract it to the desired destination path::

    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 apache user (www-data for Debian)
readable directory::

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

From the git repository
+++++++++++++++++++++++

Another solution is to get the last git version::

    cd $INSTALL_PATH
    git clone git://www.peacefrogs.net/git/chimere
    cd chimere
    git tag -l # list tagged versions
    git checkout v2.0 # checkout the desired version


Create a custom project template
********************************

There a default project provided "example_project". Copy and modify it (or
get another project based on Chimere)::

    cd $INSTALL_PATH/chimere
    cp -ra example_project mychimere_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 be at least one letter and can have a string of numbers, letters and
"_" to any length. Don't begin the name by "_" because it has special
significance in Python.

In your chimere 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 theses
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
    * ROOT_URLCONF: url configuration for your project something like:
      'mychimere_project.urls'
    * ROOT_PATH: path to the installation of Chimère
    * 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 activated)
    * JQUERY_JS_URLS: list of Jquery and Jquery-ui urls (default is appropriate
      for a Debian installation with Jquery and Jquery-ui activated)
    * JQUERY_CSS_URLS: list of Jquery and Jquery-ui urls (default is appropriate
      for a Debian installation with Jquery and Jquery-ui activated)
    * GPSBABEL: path to gpsbabel  (default is appropriate
      for a Debian installation with gpsbabel 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
    sudo chown -R user:www-data media
    sudo chmod -R g+w media

Create log file::

    mkdir /var/log/django
    touch /var/log/django/chimere.log
    sudo chown -R root:www-data /var/log/django/
    sudo 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 locale directory of chimere, you will just
need to get it compiled. This can be done with (here, **fr** stands for french).
Replace it with the appropriate language code)::

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

If your language is not available, feel free to create the default po files 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 chimère application 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 south::

    ./manage.py migrate

The database is set, congratulations!

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

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

Install mod_wsgi for apache::

    sudo apt-get install libapache2-mod-wsgi


TODO: adapt apache-wsgi.conf
Create and edit a configuration for Chimère::

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

Adapt the files *mydjango.wsgi* (with the correct sys path) and *chimere*.

To activate the website reload apache::

    sudo a2ensite chimere
    sudo /etc/init.d/apache2 reload

------------------
Base configuration
------------------

When you have installed the application there is a few simple steps to follow to configure *your* Chimère. 

Most of theses steps are done in the administration pages accessible at : http://where_is_chimere/admin
To access theses pages you have to identify you with login and password provided at the initialization of the database.

Creating areas
--------------

You probably want to define at least one default area. The configuration of
this area allow you to define the default zoom, welcome message, etc. of your
Chimère.

Creating users
--------------

If you are not the only administrator of this Chimère installation you have to create account for the other users.
Currently the process has to be done manualy.

Simply click on the Add button near Users. Give a name and a default password (the user can change it on in own later).
Then complete the other pieces of information.
Check the case: Member of the staff (or this user will not be able to log to this administration site).
To simply give this user correct rights don't add permission manualy but make this user member of a group.
Two default group are proposed: application administrator and moderator.

Detail of rights for default user/groups:

+-----------------------------------------+-------------------+---------------------------+-----------+
|                  Task                   | Application owner | Application administrator | Moderator |
+=========================================+===================+===========================+===========+
| User add/modify/delete                  |        yes        |            no             |    no     |
+-----------------------------------------+-------------------+---------------------------+-----------+
| Group add/modify/delete                 |        yes        |            no             |    no     |
+-----------------------------------------+-------------------+---------------------------+-----------+
| Property model add/modify/delete        |        yes        |            no             |    no     |
+-----------------------------------------+-------------------+---------------------------+-----------+
| News add/modify/delete                  |        yes        |            yes            |    no     |
+-----------------------------------------+-------------------+---------------------------+-----------+
| Area add/modify/delete                  |        yes        |            yes            |    no     |
+-----------------------------------------+-------------------+---------------------------+-----------+
| Icon add/modify/delete                  |        yes        |            yes            |    no     |
+-----------------------------------------+-------------------+---------------------------+-----------+
| Category/Subcategory add/modify/delete  |        yes        |            yes            |    no     |
+-----------------------------------------+-------------------+---------------------------+-----------+
| Point Of Interest add/modify/delete     |        yes        |            yes            |    yes    |
+-----------------------------------------+-------------------+---------------------------+-----------+
| Route add/modify/delete                 |        yes        |            yes            |    yes    |
+-----------------------------------------+-------------------+---------------------------+-----------+


Creating property models
------------------------

A basic installation of Chimère only permit to associate a name, a category, a
description and (for the point of interest) multimedia files for each point of
interest and each route. You may want to add more fields like phone number or
opening hours. For that all you have to do is to add a new property model.
The administration ask you for name, order (to order between other properties),
availability for the user and type (only text field and long text field are
available for the moment).
Then to make this property available it is necessary to restart your
application (and then probably to reload Apache).
All forms are then automatically updated with this new field.


Updating the design
-------------------

You can of course customize Chimère with your own CSS. To do that just edit the file static/styles.css.

After this basic configuration done the harder is done. You can do now application administration tasks.

-------------------
Site administration
-------------------

The explanation are to create new elements. To modify these elements it is the same if only some fields are already filled.

Creating news
-------------

A news system is available.
All you have to to do is to click on the Add button near News.
For each news you have to provided a name and a content. The content can contain HTML tags.
The avaibility is set with a checkbox.

Creating categories/subcategories
---------------------------------

Before adding categories you have to set some icons. Theses icons appears on the map and in the categories' box on the main map.
Be careful to resize correctly your icons. Indeed the icon will be presented at their real size on the map.
To add icons: the Add button near Icons.

Categories are in fact only containers for subcategories. You'll have to provide only a name and an order.
To add categories: the Add button near categories (quite clear now, isn't it?)

Fields of subcategories are: an associated category, a name, an icon, an order, a color and an element type.
Theses fields are mainly quite self-explainatory.
The color is used to draw routes (if this subcategory contains routes). If it a basic color it can be set with the english name (for instance: "red", "blue", "yellow" or "purple") otherwise you can put the HTML RVB code (for instance "#9227c9").
The element type is the type of element the subcategory can contain: POI, route or both.

----------
Moderation
----------

The moderation step is quite simple. It works the same with POIs and routes.
The moderator can access to all POIs (or routes) by clicking on the Modify button.
A search field is available to search by name but the more interesting is to filter POIs (or route) by state and by subcategory.
Then to modify an item you have to click on his name.
The submission can now freely modified. Compared to the main submission interface there is only on field add: the state field. To be publish in the main site the item must have the state: Available.
If an item is not revelant the Delete button permit to remove it.