diff options
Diffstat (limited to 'docs/_build/html/_sources')
| -rw-r--r-- | docs/_build/html/_sources/administration.txt | 115 | ||||
| -rw-r--r-- | docs/_build/html/_sources/configuration.txt | 165 | ||||
| -rw-r--r-- | docs/_build/html/_sources/customisation.txt | 24 | ||||
| -rw-r--r-- | docs/_build/html/_sources/import_export.txt | 14 | ||||
| -rw-r--r-- | docs/_build/html/_sources/index.txt | 17 | ||||
| -rw-r--r-- | docs/_build/html/_sources/install-1.x.txt | 353 | ||||
| -rw-r--r-- | docs/_build/html/_sources/install.txt | 274 | ||||
| -rw-r--r-- | docs/_build/html/_sources/upgrade.txt | 313 |
8 files changed, 1275 insertions, 0 deletions
diff --git a/docs/_build/html/_sources/administration.txt b/docs/_build/html/_sources/administration.txt new file mode 100644 index 0000000..db7e078 --- /dev/null +++ b/docs/_build/html/_sources/administration.txt @@ -0,0 +1,115 @@ +.. -*- coding: utf-8 -*- +.. _administration: + +============== +Administration +============== + +:Author: Étienne Loks +:date: 2012-10-08 +:Copyright: CC-BY 3.0 + +This documents presents the administration of Chimère. +The version has been updated for version 2.0.0. + + +Administration pages presentation +--------------------------------- + +Administration pages accessible at: http://where_is_your_chimere/admin/ + +Don't forget the ending slash in the URL. + +Identification +************** + +First of all, you'll have to identify yourself with the login and password +provided. + +.. image:: _static/chimere_admin_00.png + + +Main page +********* + +Once authentified you'll have access to the main admin page. + +This looks like this: + +.. image:: _static/chimere_admin_01.png + +#. links to this **Documentation**, to the **Change password** form and to + **Log out** +#. a list of recent actions made with this account +#. an application title, most of your action will be in the **Chimere** + application +#. an item inside the application. From these page you can **Add** a new item or + consult/**Change** items. The **Add** link lead to the new `Item form`_. The + **Change** link lead to the `Item list`_. The `Item list`_ is also available + by clicking on the item label. + + +Item list +********* + +.. image:: _static/chimere_admin_02.png + +#. path in the admin site. This is a convenient shortcut to come back to the + main page. +#. link to create a new item from the item list +#. search items by word (not available for all type of items) +#. this filter box permit to filter current entries with some criteria (not + available for all type of items) +#. the header of the table is clickable. Click on an header sort the items by + this header (ascending or descending). Multiple header sort is possible (the + number on the right of the header explain the order of sorting). +#. each item can be checked (for applying an action) or selected (by clicking on + the first column) to see the detail and possibly edit, delete it. + +Item form +********* + +.. image:: _static/chimere_admin_03.png + +#. fields for the selected item (or blank if it is a new item) are displayed in + this form. A few of the fields concerning an item are read-only and a few of + them are hidden. Mandatory fields have their label in bold. Changes on theses + fields are only effective once the form is submitted. +#. for some items there are associated sub-items. Theses associated items can be + modified in this form. If there are many sub-items associated for the current + item, they can be ordered by drag and drop. +#. the form has to be validated by one of theses actions buttons. They are + self-explanatory. +Creating news +------------- + +A news system is available. +All you have to to do is to click on the Add button near News. +For each news you have to provided a name and a content. The content can contain HTML tags. +The avaibility is set with a checkbox. + +Creating categories/subcategories +--------------------------------- + +Before adding categories you have to set some icons. Theses icons appears on the map and in the categories' box on the main map. +Be careful to resize correctly your icons. Indeed the icon will be presented at their real size on the map. +To add icons: the Add button near Icons. + +Categories are in fact only containers for subcategories. You'll have to provide only a name and an order. +To add categories: the Add button near categories (quite clear now, isn't it?) + +Fields of subcategories are: an associated category, a name, an icon, an order, a color and an element type. +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. + +Moderation +---------- + +The moderation step is quite simple. It works the same with POIs and routes. +The moderator can access to all POIs (or routes) by clicking on the Modify button. +A search field is available to search by name but the more interesting is to filter POIs (or route) by state and by subcategory. +Then to modify an item you have to click on his name. +The submission can now freely modified. Compared to the main submission interface there is only on field add: the state field. To be publish in the main site the item must have the state: Available. +If an item is not revelant the Delete button permit to remove it. + diff --git a/docs/_build/html/_sources/configuration.txt b/docs/_build/html/_sources/configuration.txt new file mode 100644 index 0000000..f8bed2b --- /dev/null +++ b/docs/_build/html/_sources/configuration.txt @@ -0,0 +1,165 @@ +.. -*- coding: utf-8 -*- + +============= +Configuration +============= + +:Author: Étienne Loks +:date: 2012-10-08 +:Copyright: CC-BY 3.0 + +This documents presents the first steps to configure your Chimère. + +The version has been updated for version 2.0.0. + +If an usage to the CLI is required, your session has to be initialised with +theses environment variables:: + + CHIMERE_PATH=/srv/chimere # change with your installation path + CHIMERE_LOCALNAME=mychimere # change with your local project name + CHIMERE_APP_PATH=$CHIMERE_PATH/$CHIMERE_LOCALNAME + + +When you have installed the application there is a few simple steps to follow to +configure *your* Chimère. + +Most of theses steps are done in the web administration pages. + +If you are not familiar with *Django-like* administration pages you can look +at the first paragraph of :ref:`administration` where it is presented. + +To access theses pages you have to identify you with an account with *staff* and +*superuser* status. + +A *superuser* account is created at the initialization of the database. + + +Managing areas +-------------- + +An *Area* is the base of your map. It defines: + +* a name: a human readable label for this area. +* a welcome message (*not mandatory*): this message is displayed once a day per + user arriving on the map. +* a map bounding box: this is the default area to display when arriving on the + map. +* restriction on the bounding box: if set to restricted, the end user can't pan + outside the defined bounding box. +* available layers (*not mandatory* OSM Mapnik is used by default): OSM Mapnik + render, OSM MapQuest render, OSM Transport Map render, OSM CycleMap are + available by default. You can add new custom layer cf. :ref:`managing-layers`. +* categories restriction (*not mandatory*): if no restriction is set all + categories are available. +* default checked categories (*not mandatory*). +* an external CSS file (*not mandatory*): an URL to an external CSS file. +* if categories are displayed dynamically (if dynamically is set, the end user + only view categories witch have items on the map section the user currently + see). +* an associated URN (*not mandatory*): the name of the area as a web ressource. + In practice, if the area is not the default area the URN is used at the end of + the default URL to access to this area. This is not mandatory but necessary + for each area that is not the default one. + +*Areas* are customizable directly on the web administration interface in +*Chimere/Areas*. + +As there is little chance that the default area is appropriate for you, you'll +have to set at least one default area. + +Adding many area can be a mean to show your map in different flavors. + +Managing users +-------------- + +If you are not the only administrator/moderator of this Chimère installation +you have to create and manage account for the other users. + +You can create a new *superuser* account with the CLI:: + + ./manage.py createsuperuser + +User password can be changed with the CLI (useful if you have forgotten your +password):: + + ./manage.py changepassword username + +*Users* are customizable directly on the web administration interface in +*Auth/User*. + +To create a new account, simply click on the Add button near Users. Give a name +and a default password (the user can change it on in own later). + +Then complete the other pieces of information. + +Check the case: *Staff status* (or this user will not be able to log to +the administration website). + +If this account is a new technical administrator, check *Superuser status* (this +user must be trustworthy!). Otherwise you'll have to give permissions to this +new user. It is easier to don't add permission manually but make this user +member of a group. + +Two type of default group are proposed: application administrator and moderator. + +Moderator are limited to an *Area* (they only see items that are inside the +bounding box). If a moderator manage many areas you'll have to select many +groups. + +Detail of rights for default user/groups: + ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Task | Technical administrator | Application administrator | Moderator | ++=========================================+=========================+===========================+===========+ +| User add/modify/delete | yes | no | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Group add/modify/delete | yes | no | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Property model add/modify/delete | yes | no | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Import add/modify/delete | yes | no | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Layer add/modify/delete | yes | no | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| News add/modify/delete | yes | yes | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Area add/modify/delete | yes | yes | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Icon add/modify/delete | yes | yes | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Color/Color theme add/modify/delete | yes | yes | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Category/Subcategory add/modify/delete | yes | yes | no | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Point Of Interest add/modify/delete | yes | yes | yes | ++-----------------------------------------+-------------------------+---------------------------+-----------+ +| Route add/modify/delete | yes | yes | yes | ++-----------------------------------------+-------------------------+---------------------------+-----------+ + + +Creating property models +------------------------ + +A basic installation of Chimère permit to associate a name, a category, a +description, dates, multimedia files, picture files, etc. for each geographic +item. + +You may want to add more custom fields like phone number or opening hours. For +that all you have to do is to add a new property model (*Chimere/Property +model*). + +The administration page ask you for: + +* a name, +* an order (to order between other properties), +* an availability to the end user (this can be used to set hidden properties), +* a mandatory status, +* the categories the property applied to (if no categories selected it applied + to all), +* the type: text, long text, password or date. + +To make this property available it is necessary to reload your webserver (the +property is cached). + +All forms are then automatically updated with this new field. + diff --git a/docs/_build/html/_sources/customisation.txt b/docs/_build/html/_sources/customisation.txt new file mode 100644 index 0000000..e27be01 --- /dev/null +++ b/docs/_build/html/_sources/customisation.txt @@ -0,0 +1,24 @@ +.. -*- coding: utf-8 -*- + +===================== +Chimère customisation +===================== + +:Author: Étienne Loks +:date: 2012-10-08 +:Copyright: CC-BY 3.0 + +This documents presents the installation of Chimère. +The version has been updated for version 2.0.0. + + +Updating the design +------------------- + +You can of course customize Chimère with your own CSS. To do that just edit the file static/styles.css. + +After this basic configuration done the harder is done. You can do now application administration tasks. + +.. _managing-layers: +Managing layers +--------------- diff --git a/docs/_build/html/_sources/import_export.txt b/docs/_build/html/_sources/import_export.txt new file mode 100644 index 0000000..890a644 --- /dev/null +++ b/docs/_build/html/_sources/import_export.txt @@ -0,0 +1,14 @@ +.. -*- coding: utf-8 -*- + +===================== +Chimère import/export +===================== + +:Author: Étienne Loks +:date: 2012-10-08 +:Copyright: CC-BY 3.0 + +This documents presents the administration of Chimère. +The version has been updated for version 2.0.0. + + diff --git a/docs/_build/html/_sources/index.txt b/docs/_build/html/_sources/index.txt new file mode 100644 index 0000000..45f40e0 --- /dev/null +++ b/docs/_build/html/_sources/index.txt @@ -0,0 +1,17 @@ +.. Chimère documentation master file, created by + sphinx-quickstart on Wed Feb 15 00:42:28 2012. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Chimère's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + + install + upgrade + configuration + customisation + administration + import_export diff --git a/docs/_build/html/_sources/install-1.x.txt b/docs/_build/html/_sources/install-1.x.txt new file mode 100644 index 0000000..4c8a5b8 --- /dev/null +++ b/docs/_build/html/_sources/install-1.x.txt @@ -0,0 +1,353 @@ +.. -*- coding: utf-8 -*- + +======================================== +Chimère installation (old documentation) +======================================== + +:Author: Étienne Loks +:date: 2012-02-15 +:Copyright: CC-BY 3.0 + +This documents presents the installation of Chimère for version 1.x. This +documentation is no longer relevant for version 2. + +----------------- +Base installation +----------------- + +Installation +------------ + +Prerequisites +************* + + - `apache <http://www.apache.org/>`_ version 2.x with [mod_python http://www.modpython.org/] 3.x + + - `python <http://www.python.org/>`_ versions 2.6 or 2.7 + + - `geodjango <http://www.djangoproject.com/>`_ version 1.0 + + - `postgres <http://www.postgresql.org/>`_ version 8.x + + - `gettext <http://www.gnu.org/software/gettext/>`_ + + - `psycopg2 <http://freshmeat.net/projects/psycopg/>`_ + + - `Python Imaging Library <http://www.pythonware.com/products/pil/>`_ + + - `Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_ + + - `lxml <http://lxml.de/>`_ + +geodjango is a part of django version 1.0 but it has some specific (geographically related) additionnal dependencies: + + - `geos <http://trac.osgeo.org/geos/>`_ 3.0.x + + - `proj.4 <http://trac.osgeo.org/proj/>`_ 4.4 to 4.6 + + - `posgis <http://postgis.refractions.net/>`_ versions 1.2.1 or 1.3.x + + - `gdal <http://www.gdal.org/>`_ + + +Optionaly (but recommanded): + + - `tinymce <http://tinymce.moxiecode.com/>`_ + + - `gpsbabel <http://www.gpsbabel.org/>`_ + + +The simpliest way to obtain these packages is to get them from your favorite Linux distribution repositories (for instance python, python-django, python-beautifulsoup, tinymce, apache2, libgeos-3.2.0, proj, gdal-bin, python-gdal, python-lxml, python-psycopg2, python-imaging, gettext, postgresql-8.4 and postgresql-8.4-postgis packages for Debian Squeeze). If these packages do not exist in your distribution's repository, please refer to the applications' websites. + +Database configuration +********************** + +Now that postgres and postgis are installed, you need to create a new user for chimere:: + + createuser --echo --adduser --createdb --encrypted --pwprompt chimere-user + +Then, you have to create the database, and initialize the geographic types (adapt the paths accordingly to your needs):: + + createdb --echo --owner chimere-user --encoding UNICODE chimere "My Chimère database" + createlang plpgsql chimere + psql -d chimere -f /usr/share/postgresql-8.3-postgis/lwpostgis.sql + psql -d chimere -f /usr/share/postgresql-8.3-postgis/spatial_ref_sys.sql + +Getting the sources +******************* + +The last "stable" version is available in this `directory <http://www.peacefrogs.net/download/>`_. + +Another solution is to get the last git version:: + + git clone git://www.peacefrogs.net/git/chimere + git tag -l # list tagged versions + git checkout v1.0.0 # checkout the desired version + + +Install the sources +******************* + +Unpack and move the files in an apache user (www-data for Debian) readable directory:: + + sudo mkdir /var/local/django + cd /var/local/django + sudo tar xvjf /home/etienne/chimere-last.tar.bz2 + sudo chown -R etienne:www-data chimere + +In your chimere application directory create settings.py to fit to your configuration. +A base template is provided (settings.py.example):: + + cd chimere/chimere/ + cp settings.py.example settings.py + vim settings.py + #### + PROJECT_NAME = u'Chimère' + + ROOT_PATH = '/var/local/django/chimere/chimere/' # path to the installation of Chimère + + SERVER_URL = "http://www.peacefrogs.net/" # root of the web address of Chimère + EXTRA_URL = 'chimere/' # suffix to the web address of Chimère + BASE_URL = SERVER_URL + EXTRA_URL + EMAIL_HOST = 'localhost' # smtp of an email server to send emails + + TINYMCE_URL = SERVER_URL + 'tinymce/' + + # chimere specific + DEFAULT_CENTER = (-1.679444, 48.114722) # default center of the map + EPSG_PROJECTION = 900913 # projection used for data exchange (JSON flow) + EPSG_DISPLAY_PROJECTION = 4326 # projection used to display on the map + + # default id category to check on the map + DEFAULT_CATEGORIES = [1] # list of default category ids checked on the map + + # JS definition of the main map cf. OpenLayers documentation for more details + # to begin you can leave the default OpenStreetMap map rendered with Mapnik + MAP_LAYER = "new OpenLayers.Layer.OSM.Mapnik('Mapnik')" + + # setting the appropriate language code for your site + LANGUAGE_CODE = 'en-gb' + + # database configuration + DATABASE_ENGINE = 'postgresql_psycopg2' # leave it to 'postgresql_psycopg2' + DATABASE_NAME = 'chimere' # database name + DATABASE_USER = 'chimere-user' # database user + DATABASE_PASSWORD = 'mypassword' # database password + DATABASE_HOST = '' # set to empty string for localhost + + DATABASE_PORT = '' # set to empty string for default + + #### + +If you want to use tinymce don't forget to make it available to Chimère. + +In this same chimere directory, make a symbolic link to django's basic styles (do not forget to change the path according to your configuration, it is the last time I will recall it to you. Next time, you are on your own!):: + + ln -s /usr/share/pyshared/django/contrib/admin/media/ . + +Compiling languages +******************* + +If your language is available in the locale directory of chimere, you will just need to get it compiled. Still being in the chimere directory, this can be done with (here, "de" stands for german. Replace it with the appropriate language code):: + + django-admin compilemessages -l de + +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 "de" according to the language you chose to create):: + + django-admin makemessages -l de + +There should now be a django.po file in locale/de/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. + +Database initialisation +*********************** + +Create the appropriate tables (still being in chimère application directory):: + + ./manage.py syncdb + +You will be prompted for the creation of an administrator account (administration can be found at: http://where_is_chimere/admin). +The database is set, congratulations! + +Webserver configuration +*********************** + +Apache configuration with mod_wsgi +++++++++++++++++++++++++++++++++++ + +Install mod_wsgi for apache:: + + sudo apt-get install libapache2-mod-wsgi + + +Create and edit a configuration for Chimère:: + + sudo mkdir /var/local/django/chimere/apache + sudo cp /var/local/django/chimere/docs/conf/django.wsgi /var/local/django/chimere/apache/django.wsgi + sudo cp /var/local/django/chimere/docs/conf/apache-wsgi.conf /etc/apache2/sites-available/chimere + +Adapt the files django.wsgi (with the correct sys path) and chimere. + +To activate the website reload apache:: + + sudo a2ensite chimere + sudo /etc/init.d/apache2 reload + +Apache configuration with mod_python +++++++++++++++++++++++++++++++++++++ + +Install mod_python for apache:: + + apt-get install libapache2-mod-python + +Create and edit a configuration file for Chimère:: + + sudo vim /etc/apache2/sites-available/chimere + +Insert Apache directives for your installation:: + + # part of the address after the root of your site + <Location "/chimere/"> + # directory path to the father of the installation of Chimère + PythonPath "['/var/local/django/'] + sys.path" + SetHandler python-program + PythonHandler django.core.handlers.modpython + SetEnv DJANGO_SETTINGS_MODULE chimere.settings + # set it to on or off if in test or production environment + PythonDebug On + # put differents interpreter names if you deploy several Chimère + PythonInterpreter chimere + </Location> + +To activate the website reload apache:: + + sudo a2ensite chimere + sudo /etc/init.d/apache2 reload + + +Now that you have gone through ALL this configuration procedure (which was not that hard after all) you can configure the site. + +------------------ +Base configuration +------------------ + +When you have installed the application there is a few simple steps to follow to configure *your* Chimère. + +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 users +-------------- + +If you are not the only administrator of this Chimère installation you have to create account for the other users. +Currently the process has to be done manualy. + +Simply click on the Add button near Users. Give a name and a default password (the user can change it on in own later). +Then complete the other pieces of information. +Check the case: Member of the staff (or this user will not be able to log to this administration site). +To simply give this user correct rights don't add permission manualy but make this user member of a group. +Two default group are proposed: application administrator and moderator. + +Detail of rights for default user/groups: + ++-----------------------------------------+-------------------+---------------------------+-----------+ +| Task | Application owner | Application administrator | Moderator | ++=========================================+===================+===========================+===========+ +| User add/modify/delete | yes | no | no | ++-----------------------------------------+-------------------+---------------------------+-----------+ +| Group add/modify/delete | yes | no | no | ++-----------------------------------------+-------------------+---------------------------+-----------+ +| Property model add/modify/delete | yes | no | no | ++-----------------------------------------+-------------------+---------------------------+-----------+ +| News add/modify/delete | yes | yes | no | ++-----------------------------------------+-------------------+---------------------------+-----------+ +| Area add/modify/delete | yes | yes | no | ++-----------------------------------------+-------------------+---------------------------+-----------+ +| Icon add/modify/delete | yes | yes | no | ++-----------------------------------------+-------------------+---------------------------+-----------+ +| Category/Subcategory add/modify/delete | yes | yes | no | ++-----------------------------------------+-------------------+---------------------------+-----------+ +| Point Of Interest add/modify/delete | yes | yes | yes | ++-----------------------------------------+-------------------+---------------------------+-----------+ +| 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 +-------------------------- + +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 +------------------- + +You can of course customize Chimère with your own CSS. To do that just edit the file static/styles.css. + +After this basic configuration done the harder is done. You can do now application administration tasks. + +------------------- +Site administration +------------------- + +The explanation are to create new elements. To modify these elements it is the same if only some fields are already filled. + +Creating news +------------- + +A news system is available. +All you have to to do is to click on the Add button near News. +For each news you have to provided a name and a content. The content can contain HTML tags. +The avaibility is set with a checkbox. + +Creating categories/subcategories +--------------------------------- + +Before adding categories you have to set some icons. Theses icons appears on the map and in the categories' box on the main map. +Be careful to resize correctly your icons. Indeed the icon will be presented at their real size on the map. +To add icons: the Add button near Icons. + +Categories are in fact only containers for subcategories. You'll have to provide only a name and an order. +To add categories: the Add button near categories (quite clear now, isn't it?) + +Fields of subcategories are: an associated category, a name, an icon, an order, a color and an element type. +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 +---------- + +The moderation step is quite simple. It works the same with POIs and routes. +The moderator can access to all POIs (or routes) by clicking on the Modify button. +A search field is available to search by name but the more interesting is to filter POIs (or route) by state and by subcategory. +Then to modify an item you have to click on his name. +The submission can now freely modified. Compared to the main submission interface there is only on field add: the state field. To be publish in the main site the item must have the state: Available. +If an item is not revelant the Delete button permit to remove it. + diff --git a/docs/_build/html/_sources/install.txt b/docs/_build/html/_sources/install.txt new file mode 100644 index 0000000..2dd745b --- /dev/null +++ b/docs/_build/html/_sources/install.txt @@ -0,0 +1,274 @@ +.. -*- coding: utf-8 -*- + +============ +Installation +============ + +:Author: Étienne Loks +:date: 2012-10-08 +:Copyright: CC-BY 3.0 + +This documents presents the installation of Chimère. +The version has been updated for version 2.0.0. + +Prerequisites +************* + + - `apache <http://www.apache.org/>`_ version 2.x + - `python <http://www.python.org/>`_ versions 2.6 or 2.7 + - `django <http://www.djangoproject.com/>`_ >= version 1.4 + - `south <http://south.aeracode.org/>`_ + - `postgres <http://www.postgresql.org/>`_ >= version 8.x + - `gettext <http://www.gnu.org/software/gettext/>`_ + - `psycopg2 <http://freshmeat.net/projects/psycopg/>`_ + - `Python Imaging Library <http://www.pythonware.com/products/pil/>`_ + - `pyexiv2 <http://tilloy.net/dev/pyexiv2/>`_ + - `Beautiful Soup <http://www.crummy.com/software/BeautifulSoup/>`_ + - python-simplejson + - python-gdal + - `unidecode <http://pypi.python.org/pypi/Unidecode>_ + - `lxml <http://lxml.de/>`_ + - `jquery <http://jquery.com/>`_ version 1.7.1 or better + - `jquery-ui <http://jqueryui.com/>`_ + - `Universal Feed Parser <https://code.google.com/p/feedparser/>`_ + +geodjango is a part of django since version 1.0 but it has some specific +(geographically related) additional dependencies: + + - `geos <http://trac.osgeo.org/geos/>`_ 3.0.x + - `proj.4 <http://trac.osgeo.org/proj/>`_ 4.4 to 4.6 + - `posgis <http://postgis.refractions.net/>`_ versions 1.2.1 or 1.3.x + - `gdal <http://www.gdal.org/>`_ + + +Optionaly (but recommanded): + + - `tinymce <http://tinymce.moxiecode.com/>`_ + - `gpsbabel <http://www.gpsbabel.org/>`_ + - django-celery if you want to manage large imports + + +The simpliest way to obtain these packages is to get them from your favorite +Linux distribution repositories. For instance on Debian Wheezy:: + + apt-get install python python-django python-django-south \ + 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 gpsbabel \ + python-pyexiv2 python-feedparser javascript-common + +On Debian Squeeze (you need to activate backports):: + + apt-get install -t squeeze-backports python-django + + apt-get install python python-django-south python-beautifulsoup tinymce \ + apache2 libgeos-3.2.0 proj-bin gdal-bin python-gdal python-lxml \ + python-psycopg2 python-imaging gettext postgresql-8.4 \ + postgresql-8.4-postgis libjs-jquery libjs-jquery-ui python-simplejson \ + gpsbabel python-pyexiv2 python-feedparser javascript-common + + +If these packages do not exist in your distribution's repository, please refer +to the applications' websites. + +Database configuration +********************** + +Now that postgres and postgis are installed, you need to create a new user for +chimere:: + + su postgres + createuser --echo --adduser --createdb --encrypted --pwprompt chimere-user + +Then, you have to create the database and initialize the geographic types (adapt +the paths accordingly to your needs):: + + PG_VERSION=9.1 # 8.4 for debian Squeeze + createdb --echo --owner chimere-user --encoding UNICODE chimere "My Chimère database" + createlang plpgsql chimere # only necessary on Debian Squeeze + psql -d chimere -f /usr/share/postgresql/$PG_VERSION/contrib/postgis-1.5/postgis.sql + psql -d chimere -f /usr/share/postgresql/$PG_VERSION/contrib/postgis-1.5/spatial_ref_sys.sql + +Install the sources +******************* + +Choose a path to install your Chimère:: + + INSTALL_PATH=/var/local/django + mkdir $INSTALL_PATH + +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 + tar xvjf chimere-last.tar.bz2 + chown -R myusername:www-data chimere + +From the git repository ++++++++++++++++++++++++ + +Another solution is to get the last git version:: + + cd $INSTALL_PATH + git clone git://www.peacefrogs.net/git/chimere + cd chimere + git tag -l # list tagged versions + git checkout v2.0 # checkout the desired version + + +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 -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. +A base template is provided (local_settings.py.example) and short descriptions of +the more relevant fields are given below (at least check them). Most of theses +settings are initialized in settings.py. :: + + cd $INSTALL_PATH/chimere/mychimere_project + cp local_settings.py.sample local_settings.py + vim local_settings.py + +:Fields: + + * DATABASES: parameters for the database + * PROJECT_NAME: name of the project + * SECRET_KEY: a secret key for a particular Django installation. This is + used to provide cryptographic signing, and should be set to a unique, + unpredictable value. Change it! + * ROOT_URLCONF: url configuration for your project something like: + 'mychimere_project.urls' + * EMAIL_HOST: smtp of an email server to send emails + * TINYMCE_URL: url to tinymce path (default is appropriate for a Debian + installation with tinymce activated) + * JQUERY_JS_URLS: list of Jquery and Jquery-ui urls (default is appropriate + for a Debian installation with Jquery and Jquery-ui activated) + * JQUERY_CSS_URLS: list of Jquery and Jquery-ui urls (default is appropriate + for a Debian installation with Jquery and Jquery-ui activated) + * GPSBABEL: path to gpsbabel (default is appropriate for a Debian + installation with gpsbabel installed) + * TIME_ZONE: local time zone for this installation + * LANGUAGE_CODE: language code for this installation + +Manage media path permission:: + + cd $INSTALL_PATH/chimere/mychimere_project + chown -R user:www-data media + chmod -R g+w media + +Create log file:: + + mkdir /var/log/django + touch /var/log/django/chimere.log + chown -R root:www-data /var/log/django/ + chmod -R g+w /var/log/django/ + +Regroup static files in one path:: + + cd $INSTALL_PATH/chimere/mychimere_project + ./manage.py collectstatic + +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). +Replace it with the appropriate language code):: + + 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):: + + django-admin makemessages -l fr + +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. + +Database initialisation +*********************** + +Create the appropriate tables (still being in chimère application directory):: + + cd $INSTALL_PATH/chimere/mychimere_project + ./manage.py syncdb + +You will be prompted for the creation of an administrator account +(administration can be found at: http://where_is_chimere/admin). Then you have +to create tables managed with south:: + + ./manage.py migrate + +The database is set, congratulations! + +If you want to populate your installation with default data (don't do this on +an already populated instance!):: + + ./manage.py loaddata ../chimere/fixtures/default_data.json + +Webserver configuration +*********************** + +Apache configuration with mod_wsgi +++++++++++++++++++++++++++++++++++ + +Install mod_wsgi for apache:: + + apt-get install libapache2-mod-wsgi + + +TODO: adapt apache-wsgi.conf +Create and edit a configuration for Chimère:: + + cp $INSTALL_PATH/chimere/apache/django.wsgi \ + $INSTALL_PATH/chimere/apache/mydjango.wsgi + vim $INSTALL_PATH/chimere/apache/mydjango.wsgi + cp $INSTALL_PATH/chimere/apache/apache-wsgi.conf /etc/apache2/sites-available/chimere + vim /etc/apache2/sites-available/chimere + # create log dir + mkdir /var/log/apache2/chimere/ + +Adapt the files *mydjango.wsgi* (with the correct sys path) and Apache *chimere*. + +To activate the website reload apache:: + + a2ensite chimere + /etc/init.d/apache2 reload + diff --git a/docs/_build/html/_sources/upgrade.txt b/docs/_build/html/_sources/upgrade.txt new file mode 100644 index 0000000..f2d0d64 --- /dev/null +++ b/docs/_build/html/_sources/upgrade.txt @@ -0,0 +1,313 @@ +.. -*- coding: utf-8 -*- + +======= +Upgrade +======= + +:Author: Étienne Loks +:date: 2012-10-08 +: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 +------------------------------- + +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 +++++++++++++++ +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 libjs-jquery-ui python-pyexiv2 \ + python-feedparser javascript-common + +Debian Wheezy ++++++++++++++ + +.. code-block:: bash + + apt-get install python-django-south python-simplejson libjs-jquery-ui \ + python-pyexiv2 python-feedparser javascript-common + +If you are planing to do major import consider the install of `Celery +<http://celeryproject.org/>`_. + +.. code-block:: bash + + apt-get install python-django-celery python-kombu + +Get the new sources +------------------- + +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. + +To simplify further instructions, some environment variables are +initialized. + +.. 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 + +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. + +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 stash # if you have uncommited changes + git checkout master + git pull + git checkout $CHIMERE_LOCALNAME + git rebase $CHIMERE_TAG + +From a previous tarball installation +************************************ + +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 checkout $CHIMERE_TAG + git checkout -b $CHIMERE_LOCALNAME + + +Update basic settings +********************* + +Version 1.1 -> 1.2 +++++++++++++++++++ + +.. code-block:: bash + + CHIMERE_APP_PATH=$CHIMERE_PATH/chimere + vim $CHIMERE_APP_PATH/settings.py + +Add the line (adapted for your jquery and gpsbabel installation). + +.. code-block:: python + + 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.2 -> 2.0 +++++++++++++++++++ + +Project template +................ +Create a new project template. + +.. code-block:: bash + + cd $CHIMERE_PATH + cp -ra $CHIMERE_PATH/example_project $CHIMERE_LOCALNAME + CHIMERE_APP_PATH=$CHIMERE_PATH/$CHIMERE_LOCALNAME + +local_settings +.............. +A *local_settings* file is now used. + +.. code-block:: bash + + cd $CHIMERE_APP_PATH + cp local_settings.py.sample local_settings.py + vim local_settings.py + +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.urls**. + +logs +.... +Logging is now enabled by default in the file */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 + +Static files +............ + +Now static file are managed with *django.contrib.staticfiles*. + +.. code-block:: bash + + cd $CHIMERE_APP_PATH + ./manage.py collectstatic + +Move old static files to the new static directory. + +.. 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/ + +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 +---------------- + +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 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. + +.. 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 + # folow 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 + +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 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. + |