[686] | 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-Kernel Configuration |
---|
| 12 | ======================== |
---|
| 13 | |
---|
| 14 | As already said in introduction, an OSGeoLive virtual machine image disk has been installed on your computer, allowing you to use ZOO-Kernel in a development environment directly. Every ZOO-Project related material and source code have been placed in ``/home/user/zoo-ws-2012`` directory. We will work with file included in this directory during this workshop. |
---|
| 15 | |
---|
| 16 | .. note:: we will use ZOO-Kernel or ``zoo_loader.cgi`` script without any distinction |
---|
| 17 | in this document. |
---|
| 18 | |
---|
| 19 | As explained later, the ZOO-Kernel may require to store temporary files in ``/var/www/temp``. Depending on |
---|
| 20 | parameters set in the ``main.cfg``, cache files would be located in the same directory. |
---|
| 21 | |
---|
| 22 | .. code-block:: guess |
---|
| 23 | |
---|
| 24 | sudo mkdir /var/www/tmp |
---|
| 25 | sudo chown www-data /var/www/tmp |
---|
| 26 | |
---|
| 27 | General ZOO-Kernel settings are made in the ``main.cfg`` file located in the same |
---|
| 28 | directory as the ZOO-Kernel, so in ``/usr/lib/cgi-bin/``. You can see a typical |
---|
| 29 | ``main.cfg`` content in the following: |
---|
| 30 | |
---|
| 31 | .. code-block:: guess |
---|
| 32 | :linenos: |
---|
| 33 | |
---|
| 34 | [main] |
---|
| 35 | lang=en-US,fr-FR,ja-JP |
---|
| 36 | version=1.0.0 |
---|
| 37 | encoding=utf-8 |
---|
| 38 | serverAddress=http://localhost/zoo/ |
---|
| 39 | dataPath=/var/www/data |
---|
| 40 | tmpPath=/var/www/tmp |
---|
| 41 | tmpUrl=../tmp |
---|
| 42 | cacheDir=/var/www/cache/ |
---|
| 43 | mapserverAddress=http://localhost/cgi-bin/mapserv |
---|
| 44 | msOgcVersion=1.0.0 |
---|
| 45 | |
---|
| 46 | [identification] |
---|
| 47 | title=The ZOO-Project FOSS4G 2012 Prague Workshop |
---|
| 48 | keywords=WPS,GIS,buffer |
---|
| 49 | abstract=ZOO-Project platform 2012 .See http://www.zoo-project.org for more informations |
---|
| 50 | accessConstraints=none |
---|
| 51 | fees=None |
---|
| 52 | |
---|
| 53 | [provider] |
---|
| 54 | positionName=Developer |
---|
| 55 | providerName=ZOO-Project |
---|
| 56 | addressAdministrativeArea=Lattes |
---|
| 57 | addressDeliveryPoint=1280 Av. des Platanes |
---|
| 58 | addressCountry=fr |
---|
| 59 | phoneVoice=False |
---|
| 60 | addressPostalCode=34970 |
---|
| 61 | role=Dev |
---|
| 62 | providerSite=http://www.zoo-project.org |
---|
| 63 | phoneFacsimile=False |
---|
| 64 | addressElectronicMailAddress=gerald.fenoy@geolabs.fr |
---|
| 65 | addressCity=Lattes |
---|
| 66 | individualName=Gérald FENOY |
---|
| 67 | |
---|
| 68 | 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. |
---|
| 69 | |
---|
| 70 | From the ``[main]`` section settings are as follow: |
---|
| 71 | * ``lang``: the supported languages separated by a coma (the first is the default one), |
---|
| 72 | * ``version``: the supported WPS version, |
---|
| 73 | * ``encoding``: the default encoding of WPS Responses, |
---|
| 74 | * ``serverAddress``: the url to access your ZOO-Kernel instance, |
---|
| 75 | * ``dataPath``: the path to store data files (when MapServer support was activated, |
---|
| 76 | this directory is used to store mapfiles and data). |
---|
| 77 | * ``tmpPath``: the path to store temporary files (such as ExecuteResponse when |
---|
| 78 | storeExecuteResponse was set to true), |
---|
| 79 | * ``tmpUrl``: a url relative to ``serverAddress`` to access the temporary file, |
---|
| 80 | * ``cacheDir``: the path to store cached request files [#f1]_ (optional), |
---|
| 81 | * ``mapservAddress``: your local MapServer address (optional), |
---|
| 82 | * ``msOgcVersion``: the version for all supported OGC Web Services output [#f2]_ |
---|
| 83 | (optional). |
---|
| 84 | |
---|
| 85 | The ``[identification]`` and ``[provider]`` section are specific to OGC metadata and |
---|
| 86 | should be set [#f3]_. |
---|
| 87 | |
---|
| 88 | Obviously, you are free to add new sections to this file if you need more. Nevertheless, you have to know |
---|
| 89 | that there is some specific names you should use only for specific needs: ``[env]``, ``[lenv]`` and |
---|
| 90 | ``[senv]``. |
---|
| 91 | |
---|
| 92 | .. warning:: ``[senv]`` and ``[lenv]`` are used / produced on runtime internaly by the ZOO-Kernel and should be defined only from the Service code. |
---|
| 93 | |
---|
| 94 | The ``env`` section is used to store specific environment variables you want to be set |
---|
| 95 | prior to load your Services Provider and run your Service. A typical example, is when your |
---|
| 96 | Service requires to access to a X server running on framebuffer, then you will have to |
---|
| 97 | set the ``DISPLAY`` environnement variable, in this case you would add |
---|
| 98 | ``DISPLAY=:1`` line in your ``[env]`` section. |
---|
| 99 | |
---|
| 100 | The ``lenv`` is used to store runtime informations automatically set by the |
---|
| 101 | ZOO-Kernel before running your service and can be accesses / updated from it: |
---|
| 102 | * ``sid``: the service unique identifier, |
---|
| 103 | * ``status``: the current progress value (value between 0 and 100, percent), |
---|
| 104 | * ``cwd``: the current working directory of the ZOO-Kernel, |
---|
| 105 | * ``message``: an error message when returning ``SERVICE_FAILED`` (optional), |
---|
| 106 | * ``cookie``: the cookie your service want to return to the client (for authentication |
---|
| 107 | purpose or tracking). |
---|
| 108 | |
---|
| 109 | The ``senv`` is used to store session informations on the server side. You can then access them automatically from service if the server is requested using a valid cookie. The ZOO-Kernel will store on disk the values set in the ``senv`` maps, then load an dynamically added to the env stored in ``main.cfg``: |
---|
| 110 | * ``XXX``: the session unique identifier where ``XXX`` is the name included in the |
---|
| 111 | returned cookie. |
---|
| 112 | |
---|
| 113 | .. _cookie_example: |
---|
| 114 | |
---|
| 115 | For instance, if you get the following in your Service source code [#f4]_ : |
---|
| 116 | |
---|
| 117 | .. code-block:: python |
---|
| 118 | |
---|
| 119 | conf["lenv"]["cookie"]="XXX=XXX1000000; path=/" |
---|
| 120 | conf["senv"]={"XXX": "XXX1000000","login": "demoUser"} |
---|
| 121 | |
---|
| 122 | That means that the ZOO-Kernel will create a file ``sess_XXX1000000.cfg`` in the |
---|
| 123 | ``cacheDir`` and return the specified cookie to the client. Each time the client will |
---|
| 124 | request the ZOO-Kernel using the Cookie, it will automatically load the value stored |
---|
| 125 | before running your service. You can then easilly access this informations from your |
---|
| 126 | service source code. This functionality won't be used in the following presentation. |
---|
| 127 | |
---|
| 128 | Testing the ZOO installation with GetCapabilities |
---|
| 129 | ================================================= |
---|
| 130 | |
---|
| 131 | |
---|
| 132 | You can request ZOO-Kernel using the following link from your Internet browser: |
---|
| 133 | |
---|
| 134 | http://localhost/cgi-bin/zoo_loader.cgi?Request=GetCapabilities&Service=WPS |
---|
| 135 | |
---|
| 136 | You should get a valid Capabilities XML document, looking like the following : |
---|
| 137 | |
---|
| 138 | .. image:: ./images/GC.png |
---|
| 139 | :width: 650px |
---|
| 140 | :align: center |
---|
| 141 | |
---|
| 142 | 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: |
---|
| 143 | |
---|
| 144 | .. code-block:: bash |
---|
| 145 | |
---|
| 146 | cd /usr/lib/cgi-bin |
---|
| 147 | ./zoo_loader.cgi “request=GetCapabilities&service=WPS” |
---|
| 148 | |
---|
| 149 | The same result as in your browser will be returned, as shown in the following screenshot: |
---|
| 150 | |
---|
| 151 | .. image:: ./images/GC_CL.png |
---|
| 152 | :width: 450px |
---|
| 153 | :align: center |
---|
| 154 | |
---|
| 155 | Invoking ZOO Kernel from command line can be helpful during development process of new Services. |
---|
| 156 | |
---|
| 157 | .. rubric:: Footnotes |
---|
| 158 | |
---|
| 159 | .. [#f1] when you use GET requests passed through ``xlink:href`` the ZOO-Kernel will |
---|
| 160 | execute the request only once, the first time you will ask for this ressource and it will |
---|
| 161 | store on disk the result. The next time you will need the same feature, the cached file |
---|
| 162 | will be used which make your process running faster. If ``cachedir`` was not |
---|
| 163 | specified in the ``main.cfg`` then ``tmpPath`` value will be used. |
---|
| 164 | .. [#f2] since version 1.3dev, when MapServer is activated, your service can automatically |
---|
| 165 | return a WMS, WFS or WCS request to expose your data. Your can set here the specific |
---|
| 166 | version number you want to use to request your local MapServer setup. It depends |
---|
| 167 | mostly on the client capability to deal with specific OGC Web Services version. |
---|
| 168 | .. [#f3] since version 1.3dev, when MapServer is activated, the same metadata will be used |
---|
| 169 | for setting metadata for OGC Web Services. |
---|
| 170 | .. [#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. |
---|