diff options
Diffstat (limited to 'docs/upgrade.rst')
| -rw-r--r-- | docs/upgrade.rst | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/docs/upgrade.rst b/docs/upgrade.rst new file mode 100644 index 0000000..91bd597 --- /dev/null +++ b/docs/upgrade.rst @@ -0,0 +1,186 @@ +.. -*- coding: utf-8 -*- + +=============== +Chimère upgrade +=============== + +:Author: Étienne Loks +:date: 2012-02-15 +:Copyright: CC-BY 3.0 + +This documents presents the upgrade of Chimère to version 1.2. This +documentation is no longer relevant for version 2. + +------------------------------- +Get new version of dependencies +------------------------------- + +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. + +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.:: + + su + 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.2.0 + v1.2.1 + git checkout v1.2.1 + 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 to upgrade from version 1.0 to version 1.1 +--------------------------------------------------- + +Version 1.1 of Chimère uses Django 1.2 and with it the manner 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 + +--------------------- +Run migration scripts +--------------------- + +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. + |