[443] | 1 | .. _using_zoo_from_osgeolivevm: |
---|
| 2 | |
---|
| 3 | ******************************************************************** |
---|
| 4 | Configuration and ZOO-Kernel use |
---|
| 5 | ******************************************************************** |
---|
| 6 | |
---|
| 7 | .. contents:: Table of Contents |
---|
| 8 | :depth: 5 |
---|
| 9 | :backlinks: top |
---|
| 10 | |
---|
| 11 | ZOO-Project Installation |
---|
| 12 | ======================== |
---|
| 13 | |
---|
| 14 | To be able to follow the current material, you will have to download |
---|
| 15 | and uncompress an archive containing the dataset, ZOO-Kernel and |
---|
| 16 | required services. It was made available specifically for this workshop |
---|
| 17 | and is available at : http://www.zoo-project.org/dl/ws2013-1.tar.bz2. |
---|
| 18 | |
---|
| 19 | You should use the following commands to download then uncompress the archive |
---|
| 20 | and get it extracted with correct privileges: |
---|
| 21 | |
---|
| 22 | .. code-block:: guess |
---|
| 23 | |
---|
| 24 | wget http://www.zoo-project.org/dl/ws2013-1.tar.bz2 |
---|
| 25 | sudo tar -xvjpf ws2013-1.tar.bz2 -C / |
---|
| 26 | psql -f /var/www/temp/ws2013.sql pgrouting |
---|
| 27 | |
---|
| 28 | ZOO-Kernel Configuration |
---|
| 29 | ======================== |
---|
| 30 | |
---|
| 31 | As already said in introduction, an OSGeoLive has been booted on your computer, allowing you to use ZOO-Kernel in a development environment directly. |
---|
| 32 | |
---|
| 33 | .. note:: we will use ZOO-Kernel or ``zoo_loader.cgi`` script without any distinction |
---|
| 34 | in this document. |
---|
| 35 | |
---|
| 36 | General ZOO-Kernel settings are set in the ``main.cfg`` file located in the same |
---|
| 37 | directory as the ZOO-Kernel, so in ``/usr/lib/cgi-bin/``. You can see a typical |
---|
| 38 | ``main.cfg`` content in the following: |
---|
| 39 | |
---|
| 40 | .. code-block:: guess |
---|
| 41 | :linenos: |
---|
| 42 | |
---|
| 43 | [main] |
---|
| 44 | lang=en-US,fr-FR,ja-JP |
---|
| 45 | version=1.0.0 |
---|
| 46 | encoding=utf-8 |
---|
| 47 | serverAddress=http://localhost/zoo/ |
---|
| 48 | dataPath=/var/www/data |
---|
| 49 | tmpPath=/var/www/tmp |
---|
| 50 | tmpUrl=../tmp |
---|
| 51 | cacheDir=/var/www/cache/ |
---|
| 52 | mapserverAddress=http://localhost/cgi-bin/mapserv |
---|
| 53 | msOgcVersion=1.0.0 |
---|
| 54 | |
---|
| 55 | [identification] |
---|
| 56 | title=The ZOO-Project WPS Server FOSS4G 2013 Nottingham Workshop |
---|
| 57 | keywords=WPS,GIS,buffer |
---|
| 58 | abstract=ZOO-Project platform 2013 .See http://www.zoo-project.org for more informations |
---|
| 59 | accessConstraints=none |
---|
| 60 | fees=None |
---|
| 61 | |
---|
| 62 | [provider] |
---|
| 63 | positionName=Developer |
---|
| 64 | providerName=ZOO-Project |
---|
| 65 | addressAdministrativeArea=Lattes |
---|
| 66 | addressDeliveryPoint=1280 Av. des Platanes |
---|
| 67 | addressCountry=fr |
---|
| 68 | phoneVoice=+33670082539 |
---|
| 69 | addressPostalCode=34970 |
---|
| 70 | role=Dev |
---|
| 71 | providerSite=http://www.zoo-project.org |
---|
| 72 | phoneFacsimile=False |
---|
| 73 | addressElectronicMailAddress=gerald.fenoy@geolabs.fr |
---|
| 74 | addressCity=Lattes |
---|
| 75 | individualName=Gérald FENOY |
---|
| 76 | |
---|
| 77 | The ``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. |
---|
| 78 | |
---|
| 79 | From the ``[main]`` section settings are as follow: |
---|
| 80 | * ``lang``: the supported languages separated by a coma (the first is the default one), |
---|
| 81 | * ``version``: the supported WPS version, |
---|
| 82 | * ``encoding``: the default encoding of WPS Responses, |
---|
| 83 | * ``serverAddress``: the url to access your ZOO-Kernel instance, |
---|
| 84 | * ``dataPath``: the path to store data files (when MapServer support was activated, |
---|
| 85 | this directory is used to store mapfiles and data). |
---|
| 86 | * ``tmpPath``: the path to store temporary files (such as ExecuteResponse when |
---|
| 87 | storeExecuteResponse was set to true), |
---|
| 88 | * ``tmpUrl``: a url relative to ``serverAddress`` to access the temporary file, |
---|
| 89 | * ``cacheDir``: the path to store cached request files [#f1]_ (optional), |
---|
| 90 | * ``mapservAddress``: your local MapServer address (optional), |
---|
| 91 | * ``msOgcVersion``: the version for all supported OGC Web Services output [#f2]_ |
---|
| 92 | (optional). |
---|
| 93 | |
---|
| 94 | The ``[identification]`` and ``[provider]`` section are specific to OGC metadata and |
---|
| 95 | should be set [#f3]_. |
---|
| 96 | |
---|
| 97 | Obviously, you are free to add new sections to this file if you need more. Nevertheless, you have to know |
---|
| 98 | that there is some specific names you should use only for specific |
---|
| 99 | needs: ``[headers]``, ``[mapserver]``, ``[env]``, ``[lenv]`` and ``[senv]``. |
---|
| 100 | |
---|
| 101 | .. warning:: ``[senv]`` and ``[lenv]`` are used / produced on runtime internaly by the ZOO-Kernel and should be defined only from the Service code. |
---|
| 102 | |
---|
| 103 | The ``headers`` section is used to define your own HTTP Response |
---|
| 104 | headers. You may take a look at headers returned by web site such as |
---|
| 105 | http://www.zoo-project.org by using curl command line tool for |
---|
| 106 | instance and notice the specific heder ``X-Powered-By: Zoo-Project@Trac``. |
---|
| 107 | |
---|
| 108 | .. warning:: There is no reason to define basic headers such as |
---|
| 109 | ``Content-Type`` or ``encoding`` as they will be overwritten at runtime by the |
---|
| 110 | ZOO-Kernel. |
---|
| 111 | |
---|
| 112 | The ``mapserver`` section is used to store specific mapserver configuration parameter |
---|
| 113 | such as PROJ_LIB and GDAL_DATA or any other you want to be set to make |
---|
| 114 | your MapServer working. |
---|
| 115 | |
---|
| 116 | .. note:: the ``mapserver`` section is mainly used on WIN32 platform |
---|
| 117 | |
---|
| 118 | |
---|
| 119 | The ``env`` section is used to store specific environment variables you want to be set |
---|
| 120 | prior to load your Services Provider and run your Service. A typical example, is when your |
---|
| 121 | Service requires to access to a X server running on framebuffer, then you will have to |
---|
| 122 | set the ``DISPLAY`` environnement variable, in this case you would add |
---|
| 123 | ``DISPLAY=:1`` line in your ``[env]`` section. |
---|
| 124 | |
---|
| 125 | The ``lenv`` is used to store runtime informations automatically set by the |
---|
| 126 | ZOO-Kernel before running your service and can be accesses / updated from it: |
---|
| 127 | * ``sid``: the service unique identifier, |
---|
| 128 | * ``status``: the current progress value (value between 0 and 100, percent), |
---|
| 129 | * ``cwd``: the current working directory of the ZOO-Kernel, |
---|
| 130 | * ``message``: an error message when returning ``SERVICE_FAILED`` (optional), |
---|
| 131 | * ``cookie``: the cookie your service want to return to the client (for authentication |
---|
| 132 | purpose or tracking). |
---|
| 133 | |
---|
| 134 | The ``senv`` is used to store session informations on the server |
---|
| 135 | side. You can then access them automatically from service if the |
---|
| 136 | server is requested using a valid cookie (as defined in ``lenv > |
---|
| 137 | cookie``). The ZOO-Kernel will store on disk the values set in the |
---|
| 138 | ``senv`` maps, then load it and dynamically add its content to the one |
---|
| 139 | available in the ``main.cfg``. The ``senv`` section should contain at |
---|
| 140 | least: |
---|
| 141 | * ``XXX``: the session unique identifier where ``XXX`` is the name included in the |
---|
| 142 | returned cookie. |
---|
| 143 | |
---|
| 144 | .. _cookie_example: |
---|
| 145 | |
---|
| 146 | For instance, if you get the following in your Service source code [#f4]_ : |
---|
| 147 | |
---|
| 148 | .. code-block:: python |
---|
| 149 | |
---|
| 150 | conf["lenv"]["cookie"]="XXX=XXX1000000; path=/" |
---|
| 151 | conf["senv"]={"XXX": "XXX1000000","login": "demoUser"} |
---|
| 152 | |
---|
| 153 | That means that the ZOO-Kernel will create a file ``sess_XXX1000000.cfg`` in the |
---|
| 154 | ``cacheDir`` and return the specified cookie to the client. Each time the client will |
---|
| 155 | request the ZOO-Kernel using the Cookie, it will automatically load the value stored |
---|
| 156 | before running your service. You can then easilly access this informations from your |
---|
| 157 | service source code. This functionality won't be used in the following presentation. |
---|
| 158 | |
---|
| 159 | Testing the ZOO installation with GetCapabilities |
---|
| 160 | ================================================= |
---|
| 161 | |
---|
| 162 | |
---|
| 163 | You can request ZOO-Kernel using the following link from your Internet browser: |
---|
| 164 | |
---|
| 165 | http://localhost/cgi-bin/zoo_loader.cgi?Request=GetCapabilities&Service=WPS |
---|
| 166 | |
---|
| 167 | You should get a valid Capabilities XML document, looking like the following : |
---|
| 168 | |
---|
| 169 | .. image:: ./images/GC.png |
---|
| 170 | :width: 650px |
---|
| 171 | :align: center |
---|
| 172 | |
---|
| 173 | Please note that some Process node are returned in the ProcessOfferings section, as somes are available already on OSGeoLive DVD. You can also run a GetCapabilities request from the command line, using the following command: |
---|
| 174 | |
---|
| 175 | .. code-block:: bash |
---|
| 176 | |
---|
| 177 | cd /usr/lib/cgi-bin |
---|
| 178 | ./zoo_loader.cgi “request=GetCapabilities&service=WPS” |
---|
| 179 | |
---|
| 180 | The same result as in your browser will be returned, as shown in the following screenshot: |
---|
| 181 | |
---|
| 182 | .. image:: ./images/GC_CL.png |
---|
| 183 | :width: 450px |
---|
| 184 | :align: center |
---|
| 185 | |
---|
| 186 | Invoking ZOO Kernel from command line can be helpful during development process of new Services. |
---|
| 187 | |
---|
| 188 | .. rubric:: Footnotes |
---|
| 189 | |
---|
| 190 | .. [#f1] when you use GET requests passed through ``xlink:href`` the ZOO-Kernel will |
---|
| 191 | execute the request only once, the first time you will ask for this ressource and it will |
---|
| 192 | store on disk the result. The next time you will need the same feature, the cached file |
---|
| 193 | will be used which make your process running faster. If ``cachedir`` was not |
---|
| 194 | specified in the ``main.cfg`` then ``tmpPath`` value will be used. |
---|
| 195 | .. [#f2] since version 1.3dev, when MapServer is activated, your service can automatically |
---|
| 196 | return a WMS, WFS or WCS request to expose your data. Your can set here the specific |
---|
| 197 | version number you want to use to request your local MapServer setup. It depends |
---|
| 198 | mostly on the client capability to deal with specific OGC Web Services version. |
---|
| 199 | .. [#f3] since version 1.3dev, when MapServer is activated, the same metadata will be used |
---|
| 200 | for setting metadata for OGC Web Services. |
---|
| 201 | .. [#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. |
---|