| 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-Kernel Configuration |
---|
| 11 | --------------------------------------------------- |
---|
| 12 | |
---|
| 13 | |
---|
| 14 | As 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. |
---|
| 15 | |
---|
| 16 | .. note:: we will use ZOO-Kernel or ``zoo_loader.cgi`` script without any distinction |
---|
| 17 | in this document. |
---|
| 18 | |
---|
| 19 | General 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: |
---|
| 20 | |
---|
| 21 | .. code-block:: guess |
---|
| 22 | :linenos: |
---|
| 23 | |
---|
| 24 | [headers] |
---|
| 25 | X-Powered-By=ZOO-Project@MapMint |
---|
| 26 | |
---|
| 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=http://127.0.0.1/temp/ |
---|
| 40 | |
---|
| 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 |
---|
| 47 | |
---|
| 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=http://www.geolabs.fr |
---|
| 58 | phoneFacsimile=False |
---|
| 59 | addressElectronicMailAddress=gerald@geolabs.fr |
---|
| 60 | addressCity=Lattes |
---|
| 61 | individualName=Gérald FENOY |
---|
| 62 | |
---|
| 63 | |
---|
| 64 | 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. |
---|
| 65 | |
---|
| 66 | From 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). |
---|
| 80 | |
---|
| 81 | The ``[identification]`` and ``[provider]`` section are specific to OGC metadata and |
---|
| 82 | should be set [#f3]_. |
---|
| 83 | |
---|
| 84 | Obviously, you are free to add new sections to this file if you need |
---|
| 85 | more [#f8]_. Nevertheless, you have to know |
---|
| 86 | that there is some specific names you should use only for specific |
---|
| 87 | purposes: ``[headers]``, ``[mapserver]``, ``[env]``, ``[lenv]`` and ``[senv]``. |
---|
| 88 | |
---|
| 89 | .. warning:: ``[senv]`` and ``[lenv]`` are used / produced on runtime internaly by the ZOO-Kernel and should be defined only from the Service code. |
---|
| 90 | |
---|
| 91 | The ``headers`` section is used to define your own HTTP Response |
---|
| 92 | headers. You may take a look at headers returned by web site such as |
---|
| 93 | http://www.zoo-project.org by using curl command line tool for |
---|
| 94 | instance and notice the specific heder ``X-Powered-By: Zoo-Project@Trac``. |
---|
| 95 | |
---|
| 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. |
---|
| 99 | |
---|
| 100 | The ``mapserver`` section is used to store specific mapserver configuration |
---|
| 101 | parameters such as `PROJ_LIB` and `GDAL_DATA` or any other you want to be set to |
---|
| 102 | make your MapServer working. |
---|
| 103 | |
---|
| 104 | .. note:: the ``mapserver`` section is mainly used on WIN32 platform |
---|
| 105 | |
---|
| 106 | |
---|
| 107 | The ``env`` section is used to store specific environment variables you want to be set |
---|
| 108 | prior to load your Services Provider and run your Service. A typical example, is when your |
---|
| 109 | Service requires to access to a X server running on framebuffer, then you will have to |
---|
| 110 | set the ``DISPLAY`` environnement variable, in this case you would add |
---|
| 111 | ``DISPLAY=:1`` line in your ``[env]`` section. |
---|
| 112 | |
---|
| 113 | The ``lenv`` is used to store runtime informations automatically set by the |
---|
| 114 | ZOO-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). |
---|
| 121 | |
---|
| 122 | The ``senv`` is used to store session informations on the server |
---|
| 123 | side. You can then access them automatically from service if the |
---|
| 124 | server is requested using a valid cookie (as defined in ``lenv > |
---|
| 125 | cookie``). 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 |
---|
| 127 | available in the ``main.cfg``. The ``senv`` section should contain at |
---|
| 128 | least: |
---|
| 129 | * ``XXX``: the session unique identifier where ``XXX`` is the name included in the |
---|
| 130 | returned cookie. |
---|
| 131 | |
---|
| 132 | .. _cookie_example: |
---|
| 133 | |
---|
| 134 | For instance, if you get the following in your Service source code [#f4]_ : |
---|
| 135 | |
---|
| 136 | .. code-block:: python |
---|
| 137 | |
---|
| 138 | conf["lenv"]["cookie"]="XXX=XXX1000000; path=/" |
---|
| 139 | conf["senv"]={"XXX": "XXX1000000","login": "demoUser"} |
---|
| 140 | |
---|
| 141 | That 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 |
---|
| 143 | request the ZOO-Kernel using the Cookie, it will automatically load the value stored |
---|
| 144 | before running your service. You can then easilly access this informations from your |
---|
| 145 | service source code. This functionality won't be used in the following presentation. |
---|
| 146 | |
---|
| 147 | Testing the ZOO installation with GetCapabilities |
---|
| 148 | --------------------------------------------------- |
---|
| 149 | |
---|
| 150 | |
---|
| 151 | Once you have a main.cfg file available in the same directory as your |
---|
| 152 | ZOO-Kernel, then you can use `GetCapablities`. Indeed, to answer such |
---|
| 153 | kind of requests, the ZOO-Kernel will simply parse the `main.cfg` file |
---|
| 154 | (to gather global informations), then parse individually each zcfg |
---|
| 155 | files (if any) contained in the same directory or in sub-directories |
---|
| 156 | [#f9]_, then return a well formed `Capabilities` document. |
---|
| 157 | |
---|
| 158 | You can request ZOO-Kernel using the following link from your Internet browser: |
---|
| 159 | |
---|
| 160 | http://localhost/cgi-bin/zoo_loader.cgi?Request=GetCapabilities&Service=WPS |
---|
| 161 | |
---|
| 162 | You should get a valid Capabilities XML document, looking like the following : |
---|
| 163 | |
---|
| 164 | .. image:: ./images/GC.png |
---|
| 165 | :width: 650px |
---|
| 166 | :align: center |
---|
| 167 | |
---|
| 168 | Please note that some Process nodes are returned in the |
---|
| 169 | ProcessOfferings section, as somes are available already on OSGeoLive |
---|
| 170 | DVD. You can also run a GetCapabilities request from the command line, |
---|
| 171 | using the following command: |
---|
| 172 | |
---|
| 173 | .. code-block:: bash |
---|
| 174 | |
---|
| 175 | cd /usr/lib/cgi-bin |
---|
| 176 | ./zoo_loader.cgi “request=GetCapabilities&service=WPS” | less |
---|
| 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 the command line can be helpful during |
---|
| 185 | development process of new Services for debugging purpose. If you |
---|
| 186 | need to simulate POST request from the command line, then you can use |
---|
| 187 | the following: |
---|
| 188 | |
---|
| 189 | .. code-block:: bash |
---|
| 190 | |
---|
| 191 | cd /usr/lib/cgi-bin |
---|
| 192 | # Download the sample GetCapabilities request |
---|
| 193 | curl -o /tmp/10_wpsGetCapabilities_request.xml http://schemas.opengis.net/wps/1.0.0/examples/10_wpsGetCapabilities_request.xml |
---|
| 194 | # Define required environment settings |
---|
| 195 | export REQUEST_METHOD=POST |
---|
| 196 | export CONTENT_TYPE=text/xml |
---|
| 197 | # Run the request downloaded |
---|
| 198 | ./zoo_loader.cgi < /tmp/10_wpsGetCapabilities_request.xml | less |
---|
| 199 | |
---|
| 200 | You should have the same result as presented before. |
---|
| 201 | |
---|
| 202 | .. rubric:: Footnotes |
---|
| 203 | |
---|
| 204 | .. [#f1] when you use GET requests passed through ``xlink:href`` the ZOO-Kernel will |
---|
| 205 | execute the request only once, the first time you will ask for this ressource and it will |
---|
| 206 | store on disk the result. The next time you will need the same feature, the cached file |
---|
| 207 | will be used which make your process running faster. If ``cachedir`` was not |
---|
| 208 | specified in the ``main.cfg`` then ``tmpPath`` value will be used. |
---|
| 209 | .. [#f2] since version 1.3.0, when MapServer is activated, your service can automatically |
---|
| 210 | return a WMS, WFS or WCS request to expose your data. Your can set here the specific |
---|
| 211 | version number you want to use to request your local MapServer setup. It depends |
---|
| 212 | mostly on the client capability to deal with specific OGC Web Services version. |
---|
| 213 | .. [#f3] since version 1.3.0, when MapServer is activated, the same metadata will be used |
---|
| 214 | for setting metadata for OGC Web Services. |
---|
| 215 | .. [#f8] you can take a quick look into the mapmint ``main.cfg`` file |
---|
| 216 | which is available in `/usr/lib/cgi-bin/mm/` directory to have |
---|
| 217 | example of sections use. |
---|
| 218 | .. [#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. |
---|
| 219 | .. [#f9] sub-directories listing is available from `revision 469 <http://zoo-project.org/trac/changeset/469>`__. |
---|