Documentation: update installation and upgrade procedure.

4 files changed, 275 insertions, 163 deletions

diff --git a/apache/apache-wsgi.conf b/apache/apache-wsgi.conf
index bd6ea55..4bd2b81 100644
--- a/apache/apache-wsgi.conf
+++ b/apache/apache-wsgi.conf
@@ -2,10 +2,8 @@
   ServerName chimere.example.com
   WSGIDaemonProcess chimere processes=2 maximum-requests=500 threads=1
   WSGIProcessGroup chimere
-  WSGIScriptAlias / /var/local/chimere/chimere/apache/django.wsgi
-  Alias /static  "/var/local/chimere/example_project/static"
-  Alias /media  "/var/local/chimere/example_project/media"
-  Alias /admin-media  "/usr/lib/python2.7/dist-packages/django/contrib/admin/media/"
+  WSGIScriptAlias / /var/local/chimere/chimere/apache/mydjango.wsgi
+  Alias /static  "/var/local/chimere/mychimere_project/static"
   Alias /tinymce "/usr/share/tinymce/www"
   <Directory "/usr/share/tinymce/www/">
     Options Indexes MultiViews FollowSymLinks
diff --git a/apache/django.wsgi b/apache/django.wsgi
index dc3d9f4..6227ee2 100644
--- a/apache/django.wsgi
+++ b/apache/django.wsgi
@@ -1,5 +1,5 @@
 import os, sys
 sys.path.append('/var/local/django/chimere/')
-os.environ['DJANGO_SETTINGS_MODULE'] = 'example_project.settings'
+os.environ['DJANGO_SETTINGS_MODULE'] = 'mychimere_project.settings'
 import django.core.handlers.wsgi
 application = django.core.handlers.wsgi.WSGIHandler()
diff --git a/docs/install.rst b/docs/install.rst
index d00a1bc..427e163 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -49,7 +49,7 @@ Optionaly (but recommanded):
 
  - `tinymce <http://tinymce.moxiecode.com/>`_
  - `gpsbabel <http://www.gpsbabel.org/>`_
- - django-celery if you want to manage import
+ - django-celery if you want to manage large imports
 
 
 The simpliest way to obtain these packages is to get them from your favorite
@@ -59,7 +59,7 @@ Linux distribution repositories. For instance on Debian Wheezy::
         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
+        python-django-celery python-simplejson python-gdal gpsbabel
 
 If these packages do not exist in your distribution's repository, please refer
 to the applications' websites.
@@ -92,12 +92,24 @@ 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 /home/etienne/chimere-last.tar.bz2
+    sudo tar xvjf chimere-last.tar.bz2
     sudo chown -R myusername:www-data chimere
 
 From the git repository
@@ -112,14 +124,20 @@ Another solution is to get the last git version::
     git checkout v2.0 # checkout the desired version
 
 
-Base configuration
-******************
+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 -r example_project mychimere_project
+    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.
@@ -147,9 +165,6 @@ settings are initialized in settings.py. ::
       for a Debian installation with Jquery and Jquery-ui activated)
     * GPSBABEL: path to gpsbabel  (default is appropriate
       for a Debian installation with gpsbabel installed)
-    * CHIMERE_DEFAULT_ZOOM: default zoom on map
-    * CHIMERE_DEFAULT_CENTER: center of the map
-    * CHIMERE_DISPLAY_AREAS: display area's shortcuts
     * TIME_ZONE: local time zone for this installation
     * LANGUAGE_CODE: language code for this installation
 
@@ -171,31 +186,26 @@ Regroup static files in one path::
     cd $INSTALL_PATH/chimere/mychimere_project
     ./manage.py collectstatic
 
-Removing celery configuration
-+++++++++++++++++++++++++++++
-
-TODO
-
 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).
+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/mychimere_project
-    ./manage.py compilemessages -l fr
+    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)::
+You first need to create the default po file (of course, replace **fr**
+according to the language you choose to create)::
 
-    ./manage.py makemessages -l fr
+    django-admin makemessages -l fr
 
-There should now be a django.po file in locale/fr/LC_MESSAGES. Complete it with
-your translation.
+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.
@@ -230,13 +240,15 @@ Install mod_wsgi for apache::
 TODO: adapt apache-wsgi.conf
 Create and edit a configuration for Chimère::
 
-    sudo vim $INSTALL_PATH/chimere/apache/django.wsgi
-    sudo vim $INSTALL_PATH/chimere/apache/apache-wsgi.conf
+    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 django.wsgi (with the correct sys path) and chimere.
+Adapt the files *mydjango.wsgi* (with the correct sys path) and *chimere*.
 
 To activate the website reload apache::
 
@@ -252,6 +264,13 @@ When you have installed the application there is a few simple steps to follow to
 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
 --------------
 
@@ -288,28 +307,21 @@ Detail of rights for default user/groups:
 | Route add/modify/delete                 |        yes        |            yes            |    yes    |
 +-----------------------------------------+-------------------+---------------------------+-----------+
 
-Setting the welcome page
-------------------------
-
-The message has to be set by updating the file templates/welcome.html.
-You only have to change the message at the begin of #detail_content.
 
 Creating property models
 ------------------------
 
-A basic installation of Chimère only permit to associate a name, a category and (for the point of interest) a picture 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 automaticaly updated with this new field.
-
-Updating the detail window
---------------------------
+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.
 
-When clicking on a POI a window appear with the details.
-Particulary if you have set some new property models you may want to customize this window.
-Each property is in a paragraph with id: property_i_j (i is the order and j is the model property id - the first model property is id 1 then 2...).
-You can simply adapt the CSS file (static/styles.css) to match the desired presentation.
-If you want to really change the whole presentation you can change the template file templates/detail.html (go to the Django template documentation for details).
 
 Updating the design
 -------------------
@@ -347,12 +359,6 @@ 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.
 
-Creating areas
---------------
-
-Areas are useful to provide a quick access to a particular town, a district, etc.
-To define an area fill a name and move/zoom to the choosed location. Submit it and that's all.
-
 ----------
 Moderation
 ----------
diff --git a/docs/upgrade.rst b/docs/upgrade.rst
index 7c6eed7..8d0aefb 100644
--- a/docs/upgrade.rst
+++ b/docs/upgrade.rst
@@ -5,136 +5,205 @@ Chimère upgrade
 ===============
 
 :Author: Étienne Loks
-:date: 2012-02-15
+: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.2 to 2.x
+From version 1.1 -> 1.2
 ***********************
 
-Install `Django South <http://south.aeracode.org/>`_.
+.. code-block:: bash
 
-From version prior to 1.1 to 1.1
-********************************
+    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
 
-Upgrade Django to the 1.2 version.
-Install the `Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_ library.
+    apt-get install python-django-celery python-kombu
 
-Get the new version
+Get the new sources
 -------------------
 
-First of all get the new version of the code source. You have two choices from
-the archive or from the Git repository.
+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.
 
-Download archive from the download site
-***************************************
+To simplify further instructions, some environment variables are
+initialized.
 
-Versions are available at this `address <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 as the time of writing of
-this document).
-Extract it to the desired destination path::
+.. code-block:: bash
 
-    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
-    (...)
+    CHIMERE_PATH=/srv/chimere
+    CHIMERE_TAG=v1.2.0      # version 1.1 -> 1.2
+    CHIMERE_TAG=v2.0-RC2    # version 1.2 -> 2.0
+    CHIMERE_TAG=master      # version 2.0 -> master
+    CHIMERE_LOCALNAME=mychimere
 
-    wget http://www.peacefrogs.net/download/chimere/chimere-1.0.2.tar.bz2
-    mv chimere-1.0.2.tar.bz2 /var/local/django
-    cd /var/local/django
-    tar xvjf chimere-1.0.2.tar.bz2
-    cd chimere-1.0.2
+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.
 
-Get from the Git repository
-***************************
+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
+************************************
 
-Clone the Git repository, checkout the desired version and copy it to the
-desired destination path::
+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 tag -l
-    (...)
-    v1.0.0
-    v1.0.1
-    v1.0.2
-    git checkout v1.0.2
-    cd ..
-    mv chimere /var/local/dgango/chimere-1.0
-    cd /var/local/dgango/chimere-1.0
+    git checkout $CHIMERE_TAG
+    git checkout -b $CHIMERE_LOCALNAME
 
-Copy files from your old installation
--------------------------------------
 
-From your old installation at least copy "settings.py" and the content of
-"static/icons/" and "static/upload/" to the new installation.
-You have probably customised some styles and templates (for instance
-"styles.css", "welcome.html" and "base_user.html") don't forget to copy them and
-eventualy adapt them (if you have old vanilla version of this file comparing
-with the new one provided is easier).
+Update basic settings
+*********************
 
-Adapt settings.py
------------------
+Version 1.1 -> 1.2
+++++++++++++++++++
 
-The format of settings.py could have evolved, the easiest way to complete your
-settings.py is to compare your old settings.py.example and the new one provided.
+.. code-block:: bash
 
-Upgrade to version 2.0
-**********************
+    CHIMERE_APP_PATH=$CHIMERE_PATH/chimere
+    vim $CHIMERE_APP_PATH/settings.py
 
- - Add to the settings.py a STATIC_URL variable by default set to '/static/' (be
-   careful to change MEDIA_URL if it is already set to '/static/').
+Add the line (adapted for your jquery and gpsbabel installation).
 
- - Add the detail of TEMPLATE_CONTEXT_PROCESSORS (see settings.py.example)
+.. code-block:: python
 
-Specific upgrade from version 1.0 to version 1.1
-************************************************
+    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.1 of Chimère uses Django 1.2 and with it the way to define database
-has changed.
+Version 1.2 -> 2.0
+++++++++++++++++++
 
-Old way to define your database is::
+Project template
+................
+Create a new project template.
 
-    DATABASE_ENGINE = 'postgresql_psycopg2'
-    DATABASE_NAME = 'chimere'
-    DATABASE_USER = 'chimere-user'
-    DATABASE_PASSWORD = 'password'
-    DATABASE_HOST = 'localhost'
-    DATABASE_PORT = ''
+.. code-block:: bash
 
-The new one looks like::
+    cp -ra $CHIMERE_PATH/example_project $CHIMERE_LOCALNAME
+    CHIMERE_APP_PATH=$CHIMERE_PATH/$CHIMERE_LOCALNAME
 
-    DATABASES = {
-        'default': {
-            'NAME': 'ratatouille',
-            'ENGINE': 'django.contrib.gis.db.backends.postgis',
-            'HOST': 'localhost',
-            'PORT': '5432',
-            'USER': 'chimere-user',
-            'PASSWORD': 'password',
-        },
-    }
+local_settings
+..............
+A *local_settings* file is now used.
 
-Be careful to adapt properly your settings.py
+.. code-block:: bash
 
-Migrate database
-----------------
+    cd $CHIMERE_APP_PATH
+    cp local_settings.py.sample local_settings.py
+    vim local_settings.py
 
-From 1.2 to 2.x
-***************
+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**.
 
-Django South is now used to manage database migrations. Add 'south' to your 
-INSTALLED_APPS list in settings.py and run::
+logs
+....
+Logging is now enabled by default in the file */var/log/django/chimere.log*.
 
-    ./manage.py syncdb
-    ./manage.py migrate chimere 0001 --fake
-    ./manage.py migrate chimere
+.. 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
 ********************************
@@ -153,26 +222,64 @@ 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.
+In *settings.py* verify that **chimere.scripts** is in the *INSTALLED_APPS*.
 
-After that in the chimere directory just execute the script::
+After that in the chimere directory just execute the script.
 
+.. code-block:: bash
+
+    cd $CHIMERE_APP_PATH
     python ./scripts/upgrade
 
-Point to the new installation
------------------------------
+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
 
-Most of the job is done. You'll just have to configure your web server to serve
-the new version.
-For instance for Apache the directive is changed from::
+    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
 
-    PythonPath "['/var/local/django/chimere/'] + sys.path"
+    cd $CHIMERE_APP_PATH
+    ./manage.py syncdb
+    ./manage.py migrate chimere
+
+Update translations
+-------------------
 
-To::
+Version 1.1 -> 1.2
+******************
 
-    PythonPath "['/var/local/django/chimere-1.0.2/'] + sys.path"
+.. code-block:: bash
 
-Restart your web server and apart from web browser cache issues this should work.
+    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
 ------------------------------------------------
@@ -180,19 +287,20 @@ 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 settings.py and change::
+that edit your local_settings.py and change::
+
+    STATIC_URL = '/static/'
 
-    MEDIA_ROOT = ROOT_PATH + 'static/'
-    MEDIA_URL = '/' + EXTRA_URL + 'static/'
+to::
 
-To::
+    STATIC_URL = '/static/v2.0.0/'
 
-    MEDIA_ROOT = ROOT_PATH + 'static/v1.0.2/'
-    MEDIA_URL = '/' + EXTRA_URL + 'static/v1.0.2/'
+Then in the static directory.
 
-Then in the static directory::
+.. code-block:: bash
 
-    ln -s `pwd` v1.0.2
+    cd $CHIMERE_APP_PATH/static
+    ln -s `pwd` v2.0.0
 
-Restart the web server to apply changes.
+Restart the web server to apply this changes.