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