1 | .. _kernel_config: |
---|
2 | |
---|
3 | ZOO-Kernel configuration |
---|
4 | ======================== |
---|
5 | |
---|
6 | Main configuration file |
---|
7 | ----------------------- |
---|
8 | |
---|
9 | ZOO-Kernel general settings are defined in a configuration file called |
---|
10 | ``main.cfg``. This file is stored in the same directory as ZOO-Kernel |
---|
11 | (``/usr/lib/cgi-bin/`` in most cases). It provides usefull metadata information on your ZOO-Kernel installation. |
---|
12 | |
---|
13 | .. warning:: |
---|
14 | ZOO-Kernel (``/usr/lib/cgi-bin/zoo_loader.cgi``) and its |
---|
15 | configuration file (``/usr/lib/cgi-bin/main.cfg``) must be in the |
---|
16 | same directory. |
---|
17 | |
---|
18 | .. note:: |
---|
19 | Information contained by ``/usr/lib/cgi-bin/main.cfg`` is accessible from WPS Services at runtime, so when *Execute* requests are used. |
---|
20 | |
---|
21 | Default main.cfg |
---|
22 | ............................... |
---|
23 | |
---|
24 | An example *main.cfg* file is given here as reference. |
---|
25 | |
---|
26 | .. code-block:: guess |
---|
27 | :linenos: |
---|
28 | |
---|
29 | [headers] |
---|
30 | X-Powered-By=ZOO@ZOO-Project |
---|
31 | |
---|
32 | [main] |
---|
33 | version=1.0.0 |
---|
34 | encoding=utf-8 |
---|
35 | dataPath=/var/data |
---|
36 | tmpPath=/var/www/temp |
---|
37 | cacheDir=/var/www/cache |
---|
38 | sessPath=/tmp |
---|
39 | serverAddress=http://localhost/cgi-bin/zoo_loader.cgi |
---|
40 | lang=fr-FR,ja-JP |
---|
41 | language=en-US |
---|
42 | mapserverAddress=http://localhost/cgi-bin/mapserv.cgi |
---|
43 | msOgcVersion=1.0.0 |
---|
44 | tmpUrl=http:/localhost/temp/ |
---|
45 | cors=false |
---|
46 | |
---|
47 | [identification] |
---|
48 | keywords=t,ZOO-Project, ZOO-Kernel,WPS,GIS |
---|
49 | title=ZOO-Project demo instance |
---|
50 | abstract= This is ZOO-Project, the Open WPS platform. |
---|
51 | accessConstraints=none |
---|
52 | fees=None |
---|
53 | |
---|
54 | [provider] |
---|
55 | positionName=Developer |
---|
56 | providerName=GeoLabs SARL |
---|
57 | addressAdministrativeArea=False |
---|
58 | addressDeliveryPoint=1280, avenue des Platanes |
---|
59 | addressCountry=fr |
---|
60 | phoneVoice=+33467430995 |
---|
61 | addressPostalCode=34970 |
---|
62 | role=Dev |
---|
63 | providerSite=http://geolabs.fr |
---|
64 | phoneFacsimile=False |
---|
65 | addressElectronicMailAddress=gerald@geolabs.fr |
---|
66 | addressCity=Lattes |
---|
67 | individualName=Gerald FENOY |
---|
68 | |
---|
69 | |
---|
70 | Main section |
---|
71 | ............................... |
---|
72 | |
---|
73 | The main.cfg ``[main]`` section parameters are explained bellow. |
---|
74 | |
---|
75 | * ``version``: Supported WPS version. |
---|
76 | * ``encoding``: Default encoding of WPS Responses. |
---|
77 | * ``dataPath``: Path to the directory where data files are stored (used to store mapfiles and data when MapServer support is activated). |
---|
78 | * ``tmpPath``: Path to the directory where temporary files are stored (such as *ExecuteResponse* when *storeExecuteResponse* is set to true). |
---|
79 | * ``tmpUrl``: URL to access the temporary files directory (cf. ``tmpPath``). |
---|
80 | * ``cacheDir``: Path to the directory where cached request files [#f1]_ are stored (optional). |
---|
81 | * ``serverAddress``: URL to the ZOO-Kernel instance. |
---|
82 | * ``mapservAddress``: URL to the MapServer instance (optional). |
---|
83 | * ``msOgcVersion``: Version of all supported OGC Web Services output [#f2]_ |
---|
84 | (optional). |
---|
85 | * ``lang``: Supported natural languages separated by a coma (the first is the default one), |
---|
86 | * ``cors``: Define if the ZOO-Kernel should support `Cross-Origin |
---|
87 | Resource Sharing <https://www.w3.org/TR/cors/>`__. If this |
---|
88 | paramater is not defined, then the ZOO-Kernel won't support CORS. |
---|
89 | * ``servicePath``: Define a specific location to search for services |
---|
90 | rather than using the ZOO-Kernel directory. If this parameter is |
---|
91 | not defined, then the ZOO-Kernel will search for services using its |
---|
92 | directory. |
---|
93 | |
---|
94 | In case you have activated the MapServer support, please refer to |
---|
95 | :ref:`this specific section <kernel-mapserver-main.cfg>`. |
---|
96 | |
---|
97 | |
---|
98 | Identification and Provider |
---|
99 | .......................................... |
---|
100 | |
---|
101 | The ``[identification]`` and ``[provider]`` sections are not ZOO-Project |
---|
102 | specific. They provide OGC metadata [#f3]_ and should be set according |
---|
103 | to the `XML Schema Document |
---|
104 | <http://schemas.opengis.net/ows/1.1.0/ows19115subset.xsd>`__ which |
---|
105 | encodes the parts of ISO 19115 used by the common |
---|
106 | *ServiceIdentification* and *ServiceProvider* sections of the |
---|
107 | *GetCapabilities* operation response, known as the service metadata |
---|
108 | XML document. |
---|
109 | |
---|
110 | Details of the common OWS 1.1.0 *ServiceIdentification* section can be |
---|
111 | found in this `XML Schema Document |
---|
112 | <http://schemas.opengis.net/ows/1.1.0/owsServiceIdentification.xsd>`__. |
---|
113 | |
---|
114 | Details of the common OWS 1.1.0 *ServiceProvider* section can be |
---|
115 | found in this `XML Schema Document |
---|
116 | <http://schemas.opengis.net/ows/1.1.0/owsServiceProvider.xsd>`__. |
---|
117 | |
---|
118 | |
---|
119 | Additional sections |
---|
120 | -------------------------------- |
---|
121 | |
---|
122 | Headers section |
---|
123 | ............................... |
---|
124 | |
---|
125 | The ``[headers]`` section can be set in order to define a specific HTTP |
---|
126 | Response header, which will be used for every response. As an example, |
---|
127 | you can check http://zoo-project.org using *curl* command line tool |
---|
128 | and notice the specific header *X-Powered-By: Zoo-Project@Trac*. |
---|
129 | |
---|
130 | In case you want to allow CORS support for POST requests coming from |
---|
131 | ``myhost.net``, then you should define the following minimal |
---|
132 | parameters in this section: |
---|
133 | |
---|
134 | .. code-block:: guess |
---|
135 | :linenos: |
---|
136 | |
---|
137 | Access-Control-Allow-Origin=myhost.net |
---|
138 | Access-Control-Allow-Methods=POST |
---|
139 | Access-Control-Allow-Headers=content-type |
---|
140 | |
---|
141 | |
---|
142 | env section |
---|
143 | ............................... |
---|
144 | |
---|
145 | The ``[env]`` section can be used to store specific environment |
---|
146 | variables to be set prior the loading of *Services Provider* and Service execution. |
---|
147 | |
---|
148 | A typical example is when a Service requires the access to a X server |
---|
149 | running on *framebuffer*, which takes to set the DISPLAY environnement |
---|
150 | variable, as follow: |
---|
151 | |
---|
152 | .. code-block:: guess |
---|
153 | :linenos: |
---|
154 | |
---|
155 | [env] |
---|
156 | DISPLAY=:1 |
---|
157 | |
---|
158 | In case you have activated the OTB support, please refer to :ref:`this |
---|
159 | specific section <kernel-orfeotoolbox-main.cfg>`. |
---|
160 | |
---|
161 | lenv section |
---|
162 | ............................... |
---|
163 | |
---|
164 | The ``lenv`` section is used by the ZOO-Kernel to store runtime informations |
---|
165 | before the execution of a WPS service, it contains the following |
---|
166 | parameters: |
---|
167 | |
---|
168 | * ``sid`` (r): The WPS Service unique identifier, |
---|
169 | * ``status`` (rw): The current progress value ( a value between 0 and |
---|
170 | 100 in percent (**%**) ), |
---|
171 | * ``cwd`` (r): The current working directory of ZOO-Kernel, |
---|
172 | * ``message`` (rw): An error message used when ``SERVICE_FAILED`` is returned (optional), |
---|
173 | * ``cookie`` (rw): The cookie to be returned to the client (for |
---|
174 | example for authentication purpose). |
---|
175 | * ``file.pid`` (r): The file used by the ZOO-Kernel to store process identifier. |
---|
176 | * ``file.sid`` (r): The file used by the ZOO-Kernel to store service identifier. |
---|
177 | * ``file.responseInit`` (r): The file used by the ZOO-Kernel to store |
---|
178 | the initial (then final) WPS response. |
---|
179 | * ``file.responseFinal`` (r): The file used by the ZOO-Kernel to |
---|
180 | temporary store the final WPS response. |
---|
181 | |
---|
182 | renv section |
---|
183 | ............................... |
---|
184 | |
---|
185 | The ``renv`` section is automatically created by the ZOO-Kernel before |
---|
186 | the execution of a WPS service, it contains all the environment |
---|
187 | variables available at runtime (so including the header fields in case |
---|
188 | it is used through http, refer to [https://tools.ietf.org/html/rfc3875 |
---|
189 | rfc3875] for more details). |
---|
190 | |
---|
191 | |
---|
192 | senv section |
---|
193 | ............................... |
---|
194 | |
---|
195 | The ``senv`` section can be used to store sessions information on the |
---|
196 | server side. Such information can then be accessed automatically from |
---|
197 | the Service if the server is requested using a valid cookie (as |
---|
198 | defined in ``lenv`` section). ZOO-Kernel will store the values set in the |
---|
199 | ``senv`` maps on disk, load it and dynamically replace its content to |
---|
200 | the one in the ``main.cfg``. The ``senv`` section must contain the |
---|
201 | following parameter at least: |
---|
202 | |
---|
203 | * ``XXX``: The session unique identifier where ``XXX`` is the name |
---|
204 | included in the cookie which is returned. |
---|
205 | |
---|
206 | .. _cookie_example: |
---|
207 | |
---|
208 | For instance, adding the following in the Service source code : |
---|
209 | |
---|
210 | .. code:: python |
---|
211 | |
---|
212 | conf["lenv"]["cookie"]="XXX=XXX1000000; path=/" |
---|
213 | conf["senv"]={"XXX": "XXX1000000","login": "demoUser"} |
---|
214 | |
---|
215 | means that ZOO-Kernel will create a file named ``sess_XXX1000000.cfg`` |
---|
216 | in the ``cacheDir`` directory, and will return the specified cookie to the client. Each time the client will |
---|
217 | request ZOO-Kernel using this cookie, it will automatically load the |
---|
218 | value stored before the Service execution. |
---|
219 | |
---|
220 | .. _zoo_activate_db_backend: |
---|
221 | |
---|
222 | Database section |
---|
223 | ............................... |
---|
224 | |
---|
225 | The database section allows to configure the |
---|
226 | :ref:`ZOO-Kernel optional database support <zoo_install_db_backend>`. |
---|
227 | |
---|
228 | .. code-block:: guess |
---|
229 | |
---|
230 | [database] |
---|
231 | dbname=zoo_project |
---|
232 | port=5432 |
---|
233 | user=username |
---|
234 | host=127.0.0.1 |
---|
235 | type=PG |
---|
236 | schema=public |
---|
237 | |
---|
238 | This will generate strings to be passed to GDAL to connect the |
---|
239 | database server: |
---|
240 | |
---|
241 | .. code-block:: guess |
---|
242 | |
---|
243 | <type>:host=<host> port=<port> user=<user> dbname=<dbname> |
---|
244 | |
---|
245 | |
---|
246 | With the previous database section, it will give the following: |
---|
247 | |
---|
248 | .. code-block:: guess |
---|
249 | |
---|
250 | PG:"dbname=zoo_project host=127.0.0.1 port=5432 user=username" |
---|
251 | |
---|
252 | Please refer to this `section <zoo_create_db_backend>`_ to learn how |
---|
253 | to setup the database. |
---|
254 | |
---|
255 | |
---|
256 | .. rubric:: Footnotes |
---|
257 | |
---|
258 | .. [#f1] If GET requests are passed through ``xlink:href`` to the ZOO-Kernel , the latter will execute the request the first time and store the result on disk. The next time the same request is executed, the cached file will be used and this will make your process run much faster. If ``cachedir`` was not specified in the ``main.cfg`` then the ``tmpPath`` value will be used. |
---|
259 | .. [#f2] Usefull when the :ref:`kernel-mapserver` is activated (available since ZOO-Project version 1.3.0). |
---|
260 | .. [#f3] ZOO-Kernel and MapServer are sharing the same metadata for OGC Web Services if the :ref:`kernel-mapserver` is activated. |
---|
261 | |
---|
262 | |
---|