diff options
Diffstat (limited to 'docs/upgrade.rst')
| -rw-r--r-- | docs/upgrade.rst | 328 |
1 files changed, 218 insertions, 110 deletions
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. |