source: trunk/docs/workshop/2014/using_zoo_from_osgeolivevm.txt @ 574

Last change on this file since 574 was 574, checked in by djay, 9 years ago

Add 2014 workshop material.

  • Property svn:keywords set to HeadURL Date Author Id Rev
File size: 10.0 KB
1.. _using_zoo_from_osgeolivevm:
4Configuration and ZOO-Kernel use
7.. contents:: Table of Contents
8    :depth: 5
9    :backlinks: top
11ZOO-Kernel Configuration
14As already said in introduction, an OSGeoLive Virtual Machine has been booted on your computer, allowing you to use ZOO-Kernel in a development environment directly.
16.. note:: we will use ZOO-Kernel or ``zoo_loader.cgi`` script without any distinction
17    in this document.
19General ZOO-Kernel settings are set in the ``main.cfg`` file located in the same directory as the ZOO-Kernel, so in ``/usr/lib/cgi-bin/``. This informations will be accessible from each services at runtime, so when you wil use Execute requests. You can see a typical ``main.cfg`` content in the following:
21.. code-block:: guess
22    :linenos:
24    [headers]
25    X-Powered-By=ZOO-Project@MapMint
27    [main]
28    encoding=utf-8
29    dataPath=/var/data
30    tmpPath=/var/www/temp
31    cacheDir=/var/www/cache
32    version=1.0.0
33    sessPath=/tmp
34    msOgcVersion=1.0.0
35    serverAddress=http://localhost/cgi-bin/mm/zoo_loader.cgi
36    lang=fr-FR,ja-JP
37    language=en-US
38    mapserverAddress=http://localhost/cgi-bin/mapserv.cgi
39    tmpUrl=
41    [identification]
42    keywords=WPS,GIS,buffer,MapMint,ZOO-Project
43    title=ZOO-Project Workshop - FOSS4G 2014
44    abstract= Deploying Web Processing Services using ZOO-Project – Examples of Python based WPS using PgRouting
45    accessConstraints=none
46    fees=None
48    [provider]
49    positionName=Developer
50    providerName=GeoLabs SARL
51    addressAdministrativeArea=False
52    addressDeliveryPoint=1280, avenue des Platanes
53    addressCountry=fr
54    phoneVoice=+33467430995
55    addressPostalCode=34970
56    role=Dev
57    providerSite=
58    phoneFacsimile=False
60    addressCity=Lattes
61    individualName=Gérald FENOY
64The ``main.cfg`` file contains metadata informations about the identification and provider but also some important settings. The file is composed of various sections, namely ``[main]``, ``[identification]`` and ``[provider]`` per default.
66From the ``[main]`` section settings are as follow:
67 * ``lang``: the supported languages separated by a coma (the first is the default one),
68 * ``version``: the supported WPS version,
69 * ``encoding``: the default encoding of WPS Responses,
70 * ``serverAddress``: the url to access your ZOO-Kernel instance,
71 * ``dataPath``: the path to store data files (when MapServer support was activated,
72   this directory is used to store mapfiles and data).
73 * ``tmpPath``: the path to store temporary files (such as ExecuteResponse when
74   storeExecuteResponse was set to true),
75 * ``tmpUrl``: a url relative to ``serverAddress`` to access the temporary file,
76 * ``cacheDir``: the path to store cached request files [#f1]_ (optional),
77 * ``mapservAddress``: your local MapServer address (optional),
78 * ``msOgcVersion``: the version for all supported OGC Web Services output [#f2]_
79   (optional).
81The ``[identification]`` and ``[provider]`` section are specific to OGC metadata and
82should be set [#f3]_.
84Obviously, you are free to add new sections to this file if you need
85more [#f8]_. Nevertheless, you have to know
86that there is some specific names you should use only for specific
87purposes: ``[headers]``, ``[mapserver]``, ``[env]``, ``[lenv]`` and ``[senv]``.
89.. warning:: ``[senv]`` and ``[lenv]`` are used / produced on runtime internaly by the ZOO-Kernel and should be defined only from the Service code.
91The ``headers`` section is used to define your own HTTP Response
92headers. You may take a look at headers returned by web site such as
93 by using curl command line tool for
94instance and notice the specific heder ``X-Powered-By: Zoo-Project@Trac``.
96.. warning:: There is no reason to define basic headers such as
97    ``Content-Type`` or ``encoding`` as they will be overwritten at runtime by the
98    ZOO-Kernel.
100The ``mapserver`` section is used to store specific mapserver configuration
101parameters such as `PROJ_LIB` and `GDAL_DATA` or any other you want to be set to
102make your MapServer working.
104.. note:: the ``mapserver`` section is mainly used on WIN32 platform
107The ``env`` section is used to store specific environment variables you want to be set
108prior to load your Services Provider and run your Service. A typical example, is when your
109Service requires to access to a X server running on framebuffer, then you will have to
110set the ``DISPLAY`` environnement variable, in this case you would add
111``DISPLAY=:1`` line in your ``[env]`` section.
113The ``lenv`` is used to store runtime informations automatically set by the
114ZOO-Kernel before running your service and can be accesses / updated from it:
115 * ``sid`` (r): the service unique identifier,
116 * ``status`` (rw): the current progress value (value between 0 and 100, percent),
117 * ``cwd`` (r): the current working directory of the ZOO-Kernel,
118 * ``message`` (rw): an error message when returning ``SERVICE_FAILED`` (optional),
119 * ``cookie`` (rw): the cookie your service want to return to the client (for authentication
120   purpose or tracking).
122The ``senv`` is used to store session informations on the server
123side. You can then access them automatically from service if the
124server is requested using a valid cookie (as defined in ``lenv >
125cookie``). The ZOO-Kernel will store on disk the values set in the
126``senv`` maps, then load it and dynamically add its content to the one
127available in the ``main.cfg``. The ``senv`` section should contain at
129 * ``XXX``: the session unique identifier where ``XXX`` is the name included in the
130    returned cookie.
132.. _cookie_example:
134For instance, if you get the following in your Service source code [#f4]_ :
136.. code-block:: python
138    conf["lenv"]["cookie"]="XXX=XXX1000000; path=/"
139    conf["senv"]={"XXX": "XXX1000000","login": "demoUser"}
141That means that the ZOO-Kernel will create a file ``sess_XXX1000000.cfg`` in the
142``cacheDir`` and return the specified cookie to the client. Each time the client will
143request the ZOO-Kernel using the Cookie, it will automatically load the value stored
144before running your service. You can then easilly access this informations from your
145service source code. This functionality won't be used in the following presentation.
147Testing the ZOO installation with GetCapabilities
150Once you have a main.cfg file available in the same directory as your
151ZOO-Kernel, then you can use `GetCapablities`. Indeed, to answer such
152kind of requests, the ZOO-Kernel will simply parse the `main.cfg` file
153(to gather global informations), then parse individually each zcfg
154files (if any) contained in the same directory or in sub-directories
155[#f9]_, then return a well formed `Capabilities` document.
157You can request ZOO-Kernel using the following link from your Internet browser:
161You should get a valid Capabilities XML document, looking like the following :
163.. image:: ./images/GC.png
164   :width: 650px
165   :align: center
167Please note that some Process nodes are returned in the
168ProcessOfferings section, as somes are available already on OSGeoLive
169DVD. You can also run a GetCapabilities request from the command line,
170using the following command: 
172.. code-block:: bash
174    cd /usr/lib/cgi-bin
175    ./zoo_loader.cgi “request=GetCapabilities&service=WPS” | less
177The same result as in your browser will be returned, as shown in the following screenshot:
179.. image:: ./images/GC_CL.png
180   :width: 450px
181   :align: center
183Invoking ZOO Kernel from the command line can be helpful during
184development process of new Services for debugging purpose. If you
185need to simulate POST request from the command line, then you can use
186the following:
188.. code-block:: bash
190    cd /usr/lib/cgi-bin
191    # Download the sample GetCapabilities request
192    curl -o /tmp/10_wpsGetCapabilities_request.xml
193    # Define required environment settings
195    export CONTENT_TYPE=text/xml
196    # Run the request downloaded
197    ./zoo_loader.cgi < /tmp/10_wpsGetCapabilities_request.xml | less
199You should have the same result as presented before.
201.. rubric:: Footnotes
203.. [#f1] when you use GET requests passed through ``xlink:href`` the ZOO-Kernel will
204    execute the request only once, the first time you will ask for this ressource and it will
205    store on disk the result. The next time you will need the same feature, the cached file
206    will be used which make your process running faster. If ``cachedir`` was not
207    specified in the ``main.cfg`` then ``tmpPath`` value will be used.
208.. [#f2] since version 1.3.0, when MapServer is activated, your service can automatically
209    return a WMS, WFS or WCS request to expose your data. Your can set here the specific
210    version number you want to use to request your local MapServer setup. It depends
211    mostly on the client capability to deal with specific OGC Web Services version.
212.. [#f3] since version 1.3.0, when MapServer is activated, the same metadata will be used
213    for setting metadata for OGC Web Services.
214.. [#f8] you can take a quick look into the mapmint ``main.cfg`` file
215    which is available in `/usr/lib/cgi-bin/mm/` directory to have
216    example of sections use.
217.. [#f4] If you're not familiar with ZOO-Project, you can `pass <using_zoo_from_osgeolivevm#testing-the-zoo-installation-with-getcapabilities>`__  this part and come to it after the next section.
218.. [#f9] sub-directories listing is available from `revision 469 <>`__.
Note: See TracBrowser for help on using the repository browser.


Context Navigation

ZOO Sponsors

Become a sponsor !

Knowledge partners

Become a knowledge partner

Related links