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

===============
Chimère upgrade
===============

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


Before any upgrade backup the database and all your installation files
(specially if you have made changes to them).
The process for migration requires a basic knowledge of Git and Linux CLI. It is
not an easy process. A work is done to easy the upgrade in later versions (>2.0)
of Chimère.

If several versions has been published, you should repeat any upgrading steps.
For instance to upgrade from v1.1 to v2.0 you should first upgrade to v1.2 then
to v2.0. The only optional step is the integration of your customisations.

The current stable version is 2.0.
If you are considering to contribute on Chimère get the Git master.

The instruction are given for Debian Squeeze and Debian Wheezy.


Get new version of dependencies
-------------------------------

From version 1.1 -> 1.2
***********************

.. code-block:: bash

    apt-get install python-lxml libjs-jquery gpsbabel

From version 1.2 to 2.0
***********************

Debian Squeeze
++++++++++++++
Activate the backports: http://backports-master.debian.org/Instructions/
Then install the new dependencies::

    apt-get install -t squeeze-backports python-django python-django-south \
            python-simplejson

Debian Wheezy
+++++++++++++

.. code-block:: bash

    apt-get install python-django-south python-simplejson libjs-jquery-ui

If you are planing to do major import consider the install of `Celery
<http://celeryproject.org/>`_.

.. code-block:: bash

    apt-get install python-django-celery python-kombu

Get the new sources
-------------------

First of all we have to get the new version of the source code.
For this upgrade process, we are getting the source code from the Git
repository.

To simplify further instructions, some environment variables are
initialized.

.. code-block:: bash

    CHIMERE_PATH=/srv/chimere
    CHIMERE_TAG=v1.2.0      # version 1.1 -> 1.2
    CHIMERE_TAG=v2.0-RC3    # version 1.2 -> 2.0
    CHIMERE_TAG=master      # version 2.0 -> master
    CHIMERE_LOCALNAME=mychimere

Your local name is used for the name of your local git branch and the Python
package. 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.

From a previous Git installation
********************************

.. code-block:: bash

    cd $CHIMERE_PATH
    git checkout -b $CHIMERE_LOCALNAME # do it only if you haven't yet create a local branch
    git checkout master
    git pull
    git checkout $CHIMERE_LOCALNAME
    git rebase $CHIMERE_TAG

From a previous tarball installation
************************************

Remove first your old installation and get the Git version.

.. code-block:: bash

    cd $CHIMERE_PATH
    cd ..
    rm -rf $CHIMERE_PATH
    git clone git://www.peacefrogs.net/git/chimere
    cd chimere
    git checkout $CHIMERE_TAG
    git checkout -b $CHIMERE_LOCALNAME


Update basic settings
*********************

Version 1.1 -> 1.2
++++++++++++++++++

.. code-block:: bash

    CHIMERE_APP_PATH=$CHIMERE_PATH/chimere
    vim $CHIMERE_APP_PATH/settings.py

Add the line (adapted for your jquery and gpsbabel installation).

.. code-block:: python

    JQUERY_URL = SERVER_URL + 'jquery/jquery-1.4.4.min.js'
    GPSBABEL = '/usr/bin/gpsbabel'
    # simplify with an error of 5 meters
    GPSBABEL_OPTIONS = 'simplify,crosstrack,error=0.005k'

Version 1.2 -> 2.0
++++++++++++++++++

Project template
................
Create a new project template.

.. code-block:: bash

    cp -ra $CHIMERE_PATH/example_project $CHIMERE_LOCALNAME
    CHIMERE_APP_PATH=$CHIMERE_PATH/$CHIMERE_LOCALNAME

local_settings
..............
A *local_settings* file is now used.

.. code-block:: bash

    cd $CHIMERE_APP_PATH
    cp local_settings.py.sample local_settings.py
    vim local_settings.py

Report your old settings.py in local_settings.py (at least the database
configuration).
Your *ROOT_URLCONF* must be set to **value_of_your_localname.settings**.

logs
....
Logging is now enabled by default in the file */var/log/django/chimere.log*.

.. code-block:: bash

    mkdir /var/log/django
    chown www-data -R /var/log/django

Static files
............
Move old static files to the new static directory.

.. code-block:: bash

    cp -ra $CHIMERE_PATH/chimere/static/* $CHIMERE_APP_PATH/static/

Now static file are managed with *django.contrib.staticfiles*.

.. code-block:: bash

    cd $CHIMERE_APP_PATH
    ./manage.py collectstatic

Webserver configuration
.......................
If you are using Apache and WSGI to serve your Chimère, change your WSGI
configuration file to point to the correct settings:
**value_of_your_localname.settings**.

Change your webserver directive to point to the correct static directory from
**your_chimere_path/chimere/static** to
**your_chimere_path/your_local_name/static**.

Version 2.0 -> master
+++++++++++++++++++++

Update settings and static files.

.. code-block:: bash

    cp $CHIMERE_PATH/example_project/settings.py $CHIMERE_LOCALNAME
    ./manage.py collectstatic

Migrate database
----------------

From version prior to 1.2 to 1.2
********************************

Migration scripts test your installation before making changes so you probably
won't have any lost but by precaution before running theses scripts don't forget
to backup your database.
You can also make a copy of your current database into a new database and make
the new installation to this new database.

The gdal binding for python is necessary to run the upgrade scripts (available
in the python-gdal package in Debian).

If you run the migration scripts in a production environnement stop the old
instance of Chimère before executing the migration script. Perhaps prepare the
web server to point to the new installation before doing the database upgrade
(cf. next paragraph).

In *settings.py* verify that **chimere.scripts** is in the *INSTALLED_APPS*.

After that in the chimere directory just execute the script.

.. code-block:: bash

    cd $CHIMERE_APP_PATH
    python ./scripts/upgrade

From 1.2 to 2.0
***************

Django South is now used to manage database migrations. Add **south** to your 
*INSTALLED_APPS* list in *settings.py* and run.

.. code-block:: bash

    cd $CHIMERE_APP_PATH
    ./manage.py syncdb
    ./manage.py migrate chimere 0001 --fake
    ./manage.py migrate chimere

A description field is now available for markers. If you would like to move
values of an old *Property model* to this new field, a script is available.

.. code-block:: bash

    cd $CHIMERE_APP_PATH
    ../chimere/scripts/migrate_properties.py
    # folow the instructions

From 2.0 to master
******************

.. code-block:: bash

    cd $CHIMERE_APP_PATH
    ./manage.py syncdb
    ./manage.py migrate chimere

Update translations
-------------------

Version 1.1 -> 1.2
******************

.. code-block:: bash

    cd $CHIMERE_APP_PATH
    ./manage.py compilemessages

Version 1.2 -> 2.0 -> master
****************************

.. code-block:: bash

    cd $CHIMERE_PATH/chimere
    django-admin compilemessages

Force the upgrade of visitor's web browser cache
------------------------------------------------

If major changes in the javascript has be done between version, many of your
users could experience problems. There are many tricks to force the refresh
of their cache. One of them is to change the location of statics files. To do
that edit your local_settings.py and change::

    STATIC_URL = '/static/'

to::

    STATIC_URL = '/static/v2.0.0/'

Then in the static directory.

.. code-block:: bash

    cd $CHIMERE_APP_PATH/static
    ln -s `pwd` v2.0.0

Restart the web server to apply this changes.