path: root/docs/fr/upgrade.rst

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

=======
Upgrade
=======

:Auteur: Étienne Loks
:date: 2012-11-29
:Copyright: CC-BY 3.0

Ce document présente la mise à jour de Chimère.
Il a été mis à jour pour la version 2.0.0 de Chimère.

.. Warning::
   Avant toute mise à jour la base de données et toutes vos fichiers
   d'installation (en particulier si vous avez fait des changements sur
   ceux-ci).

La procédure de migration nécessite une connaissance de base de Git et la ligne
de commande Linux. Ce n'est *pas* une procédure facile. Un travail est en cours
pour faciliter les mises à jour des futures versions de Chimère (>2.0).

Si plusieurs versions de Chimère ont été publiées depuis votre installation,
vous devez répéter toutes les étapes de mise à jour.
Par exemple pour mettre à jour depuis la version 1.1 vers la version 2.0, vous
devez d'abord mettre à jour vers la version 1.2 puis vers la version 2.0.
La seule étape optionnelle est l'intégration de vos personnalisations.

La version stable actuelle est la version 2.0.

.. Note::
   Si vous souhaitez améliorer Chimère prenez la branche *master* sur Git.

Les instructions sont données pour Debian Squeeze et Debian Wheezy.


Obtenir des nouvelles versions des dépendances
----------------------------------------------

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

.. code-block:: bash

    apt-get install python-lxml libjs-jquery gpsbabel python-gdal

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

Debian Squeeze
++++++++++++++
Activez les backports: http://backports-master.debian.org/Instructions/
Puis installez les nouvelles dépendances ::

    apt-get install -t squeeze-backports python-django python-django-south \
                       python-simplejson libjs-jquery-ui python-pyexiv2 \
                       python-feedparser javascript-common libjs-jquery

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

.. code-block:: bash

    apt-get install python-django-south python-simplejson libjs-jquery-ui \
                    python-pyexiv2 python-feedparser javascript-common

Si vous envisagez de réaliser des imports importants envisagez l'installation
de `Celery <http://celeryproject.org/>`_.

.. code-block:: bash

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

Obtenir les nouvelles sources
-----------------------------

Tout d'abord vous avez à obtenir la nouvelle version du code source.
Pour la procédure d'installation, le code source doit être pris depuis
le dépôt Git.

Pour simplifier les instructions suivantes, quelques variables d'environnement
sont initialisées.

.. 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

Le nom de votre projet (*CHIMERE_LOCALNAME*) est utilisé pour le nom de la
bibliothèque Python correspondant à votre projet ainsi que votre propre
branche Git.
En tant que bibliothèque Python, ce nom doit suivre les règles de nommage des
noms de variable Python : il doit comporter au moins une lettre et peut
comporter autant de nombres et de lettres que souhaité, le caractère tiret bas
(« _ ») est accepté. N'utilisez pas de caractères accentués. Ne commencez pas
par « _ » car cela a une signification particulière en Python.


Pour une précédente installation Git
************************************

.. code-block:: bash

    cd $CHIMERE_PATH
    git checkout -b $CHIMERE_LOCALNAME # seulement si vous n'avez pas encore
                                       # créé votre branche locale
    git stash # si vous avez des changements pas encore « commités »
    git checkout master
    git pull
    git checkout $CHIMERE_LOCALNAME
    git rebase $CHIMERE_TAG

Pour une précédente installation depuis une archive
***************************************************

Supprimez d'abord votre ancienne installation et obtenez la version Git ::

.. 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


Mettre à jour les paramètres de base
************************************

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

.. code-block:: bash

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

Ajoutez les lignes suivantes (adaptez en fonction de vos installations
jquery et gpsbabel) :

.. code-block:: python

    JQUERY_URL = SERVER_URL + 'jquery/jquery-1.4.4.min.js'
    GPSBABEL = '/usr/bin/gpsbabel'
    # simplification des trajets avec une tolérance de 5 metres
    GPSBABEL_OPTIONS = 'simplify,crosstrack,error=0.005k'

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

Patron de projet
................
Créez un nouveau patron de projet :

.. code-block:: bash

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

local_settings
..............
Un fichier *local_settings* est maintenant utilisé.

.. code-block:: bash

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

Reportez vos anciens paramètres de *settings.py* vers *local_settings.py*
(au minimum la configuration de votre base de données).
Le paramètre *ROOT_URLCONF* doit être mis à la valeur
**nom_de_votre_projet.urls**.

logs
....
Par défaut, des fichiers de *log* sont maintenant écrit dans le fichier :
*/var/log/django/chimere.log*.

.. code-block:: bash

    mkdir /var/log/django
    touch /var/log/django/chimere.log
    chown www-data -R /var/log/django

Fichiers statiques
..................

Les fichiers statiques sont maintenant gérés avec *django.contrib.staticfiles*.

.. code-block:: bash

    cd $CHIMERE_APP_PATH
    ./manage.py collectstatic


Déplacez vos anciens fichiers statiques vers le nouveau répertoire :

.. code-block:: bash

    cp -ra $CHIMERE_PATH/chimere/static/* $CHIMERE_APP_PATH/static/
    cp -ra $CHIMERE_PATH/chimere/static/icons/* $CHIMERE_APP_PATH/media/icons/
    cp -ra $CHIMERE_PATH/chimere/static/upload $CHIMERE_APP_PATH/media/

Configuration du serveur Web
............................

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

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

Migration scripts test your installation before making changes so you probably
won't have any lost but by precaution before running these 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.py

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

Django South is now used to manage database migrations.

.. code-block:: bash

    cd $CHIMERE_APP_PATH
    ./manage.py syncdb
    ./manage.py migrate chimere 0001 --fake # fake the database initialisation
    ./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
    # follow 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

Forcing the refresh of visitor's web browser cache
--------------------------------------------------

If major changes in the javascript has been done between versions, 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.