diff options
Diffstat (limited to 'docs/upgrade.rst')
| -rw-r--r-- | docs/upgrade.rst | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/docs/upgrade.rst b/docs/upgrade.rst new file mode 100644 index 0000000..10548d7 --- /dev/null +++ b/docs/upgrade.rst @@ -0,0 +1,190 @@ +.. -*- coding: utf-8 -*- + +=============== +Chimère upgrade +=============== + +:Author: Étienne Loks +:date: 2012-02-15 +:Copyright: CC-BY 3.0 + +Get new version of dependencies +------------------------------- + +From version 1.2 to 2.x +*********************** + +Install `Django South <http://south.aeracode.org/>`_. + +From version prior to 1.1 to 1.1 +******************************** + +Upgrade Django to the 1.2 version. +Install the `Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_ library. + +Get the new version +------------------- + +First of all get the new version of the code source. You have two choices from +the archive or from the Git repository. + +Download archive from the download site +*************************************** + +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:: + + 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 + 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 + +Get from the Git repository +*************************** + +Clone the Git repository, checkout the desired version and copy it to the +desired destination 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 + +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). + +Adapt settings.py +----------------- + +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. + +Specific upgrade from version 1.0 to version 1.1 +*************************************************** + +Version 1.1 of Chimère uses Django 1.2 and with it the way to define database +has changed. + +Old way to define your database is:: + + DATABASE_ENGINE = 'postgresql_psycopg2' + DATABASE_NAME = 'chimere' + DATABASE_USER = 'chimere-user' + DATABASE_PASSWORD = 'password' + DATABASE_HOST = 'localhost' + DATABASE_PORT = '' + +The new one looks like:: + + DATABASES = { + 'default': { + 'NAME': 'ratatouille', + 'ENGINE': 'django.contrib.gis.db.backends.postgis', + 'HOST': 'localhost', + 'PORT': '5432', + 'USER': 'chimere-user', + 'PASSWORD': 'password', + }, + } + +Be careful to adapt properly your settings.py + +Migrate database +---------------- + +From 1.2 to 2.x +*************** + +Django South is now used to manage database migrations. Add 'south' to your +INSTALLED_APPS list in settings.py and run:: + + ./manage.py syncdb + ./manage.py migrate main 0001 --fake + ./manage.py migrate main + + +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:: + + python ./scripts/upgrade + +Point to the new installation +----------------------------- + +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:: + + PythonPath "['/var/local/django/chimere/'] + sys.path" + +To:: + + PythonPath "['/var/local/django/chimere-1.0.2/'] + sys.path" + +Restart your web server and apart from web browser cache issues this should work. + +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:: + + MEDIA_ROOT = ROOT_PATH + 'static/' + MEDIA_URL = '/' + EXTRA_URL + 'static/' + +To:: + + MEDIA_ROOT = ROOT_PATH + 'static/v1.0.2/' + MEDIA_URL = '/' + EXTRA_URL + 'static/v1.0.2/' + +Then in the static directory:: + + ln -s `pwd` v1.0.2 + +Restart the web server to apply changes. + |