source: trunk/docs/kernel/installation.txt @ 215

Last change on this file since 215 was 215, checked in by jmckenna, 13 years ago

add Debian / Ubuntu install instructions

File size: 19.6 KB
Line 
1.. _kernel-installation:
2
3Installation
4============
5
6.. contents:: Table of Contents
7    :depth: 4
8    :backlinks: top
9
10This page provides documentation on how to compile then install the ZOO Kernel on Unix and Win32 platforms.
11
12Obtaining the ZOO Kernel Source
13-------------------------------
14
15Use the following command to get the ZOO Kernel source code through Subversion:
16
17::
18
19  svn checkout http://svn.zoo-project.org/svn/trunk zoo-project
20
21For users which get a developer account, use the following:
22
23::
24
25  sed "s:\[tunnels\]:\[tunnels\]\nzoosvn = /usr/bin/ssh -p 1046:g" -i ~/.subversion/config
26  svn co svn+zoosvn://svn.zoo-project.org/var/svn/repos/trunk zoo-project
27
28The first line of the instruction above defines a specific tunnel to access the svn server through
29the SSH protocol. Indeed, the ZOO SVN server listens on the 1046 (1024+22) port rather than the default one (22).
30
31Prerequisites
32-------------
33
34The following libraries are required on your system before you can install the ZOO Kernel:
35
36- autoconf (  http://www.gnu.org/software/autoconf/ )
37- cgic (  http://www.boutell.com/cgic )
38- cURL (  http://curl.haxx.se )
39- FastCGI (  http://www.fastcgi.com )
40- Flex & Bison (  http://flex.sourceforge.net/  http://www.gnu.org/software/bison/ )
41- libxml2 (  http://xmlsoft.org )
42- OpenSSL (  http://www.openssl.org )
43- Python (  http://www.python.org )
44
45Optional libraries include:
46
47- PHP Embedded (optional) (  http://www.php.net )
48- Java SDK (optional) (  http://java.sun.com )
49- SpiderMonkey (optional) (  http://www.mozilla.org/js/spidermonkey/ )
50
51Compile libcgic
52---------------
53
54The first step is to compile libcgic from the ``zoo-project/thirds`` directory. For such a task, please use
55the following command:
56
57::
58
59  cd thirds/cgic206
60  make
61
62Make sure that a ``libcgic.a`` is created in your ``zoo-project/thirds/cgic206`` directory. If yes, then
63you can go to the next step.
64
65On Windows, rather than using the make command, please use:
66
67::
68
69  nmake /f makefile.vc.
70 
71.. warning::
72   If you don't compile libcgic first, and try to compile the ZOO Kernel, you will get an error such as *cannot find -lcgic*
73
74Unix
75----
76
77For Unix users, the ZOO Kernel comes with a GNU autoconf "configure" script that should take care of (hopefully!)
78all compilation issues for you.
79
80The configure script won't work on Windows. See section :ref:`WIN32 <win32>` for details on compiling
81on Windows systems.
82
83For the impatient
84*****************
85
86To build the ``zoo_loader.cgi`` CGI program with the default options, cd to the directory
87where you extracted the ZOO Kernel source code package and use the following commands:
88
89::
90
91  $ cd zoo-kernel
92  $ autoconf 
93  $ ./configure
94  $ make
95
96Unless something went wrong, you should have executables in the current directory for the ``zoo_loader.cgi``
97CGI program. You can copy the ``zoo_loader.cgi`` program and the ``main.cfg`` file to your HTTP server's CGI
98directory and start using it.
99
100At this step your ZOO-Kernel should work. Nevertheless, don't forget to correct the main.cfg settings
101to set ``tmpPath`` and ``tmpUrl`` to fit your web server configuration.
102
103Configure Options
104*****************
105
106Here is the list of available options as returned by *./configure --help*:
107
108::
109
110  --with-gdal-config=FILE specify an alternative gdal-config file
111  --with-xml2config=FILE  specify an alternative xml2-config file
112  --with-python=PATH      To enable python support or specify an alternative
113                          directory for python installation, disabled by
114                          default
115  --with-php=PATH         To enable php support or specify an alternative
116                          directory for php installation, disabled by default
117  --with-perl=PATH        To enable perl support or specify an alternative
118                          directory for perl installation, disabled by default
119  --with-java=PATH        To enable java support, specify a JDK_HOME,
120                          disabled by default
121  --with-js=PATH          specify --with-js=path-to-js to enable js support,
122                          specify --with-js on linux debian like, js support
123                          is disabled by default
124
125All the options are described in more details below.
126
127(Required) GDAL Support
128^^^^^^^^^^^^^^^^^^^^^^^
129
130If your gdal-config program is not found in your PATH then you can use the
131``--with-gdal-config`` option to specify its location. For instance, let's suppose that your gdal-config
132was installed in /usr/local/bin and this directory is not in your PATH, then you can use
133the following command:
134
135::
136
137  $ ./configure --with-gdal-config=/usr/local/bin/gdal-config
138
139(Required) XML2 Support
140^^^^^^^^^^^^^^^^^^^^^^^
141
142If your xml2-config program is not found in your PATH then you can use the
143``--with-xml2config`` option to specify its location. For instance, let's suppose that
144your xml2-config was installed in /usr/local/bin and this directory is not in your PATH,
145then you can use the following command:
146
147::
148
149  $ ./configure --with-xml2config=/usr/local/bin/xml2-config
150
151(Optional) Python Support
152^^^^^^^^^^^^^^^^^^^^^^^^^
153
154If you want to activate Python support for the ZOO Kernel then you will have to use the
155``--with-python`` option. If your python-config program is found in your PATH then you
156don't have to specify the path where Python was installed, such as:
157
158::
159
160  $ ./configure --with-python
161
162This assumes that python-config is found in your PATH.
163
164In the case that your python-config is not found in your PATH, then you can specify the Python
165installation directory you are using. For instance, let's suppose that you installed
166Python in /usr/local, then you can use the following command:
167
168::
169
170  $ ./configure --with-python=/usr/local
171
172This assumes that /usr/local/bin/python-config exists.
173
174(Optional) PHP Support
175^^^^^^^^^^^^^^^^^^^^^^
176
177To be able to activate PHP support for the ZOO Kernel you'll need to get a local PHP Embedded
178installation; for more information about the required configure options when compiling PHP you
179can refer to this page :
180
181     http://zoo-project.org/trac/wiki/ZooKernel/Embed/PHP
182
183If you want to activate the PHP support for the ZOO Kernel then you will have to use the
184``--with-php`` option. If your php-config program is found in your PATH then you don't have
185to specify the path where PHP was installed, then you can use the following commnd:
186
187::
188
189  $ ./configure --with-php
190
191This assumes that php-config is found in your PATH.
192
193In the case that your php-config is not found in your PATH, then you can specify the PHP installation
194directory you are using. For instance, let's suppose that you installed PHP in /usr/local,
195then you can use the following command:
196
197::
198
199  $ ./configure --with-php=/usr/local
200
201This assumes that /usr/local/bin/php-config exists.
202
203(Optional) Perl Support
204^^^^^^^^^^^^^^^^^^^^^^^
205
206If you want to activate Perl support for the ZOO Kernel then you will have to use the
207``--with-perl`` option. If you do not set any value to this option, then the perl program will
208be searched in your PATH. So in such a case, you can use the following command:
209
210::
211
212  $ ./configure --with-perl
213
214This assumes that perl is found in your PATH.
215
216In the other case, for custom Perl installations, you can set the installation directory. For instance,
217let's suppose that you installed Perl in /usr/local and /usr/local/bin is not in your PATH,
218then you can use the following command:
219
220::
221
222  $ ./configure --with-perl=/usr/local
223
224This assumes that /usr/local/bin/perl exists.
225
226(Optional) Java Support
227^^^^^^^^^^^^^^^^^^^^^^^
228
229If you want to activate Java support for the ZOO Kernel then you will have to use the
230``--with-java`` option and set the installation path of your Java SDK. For instance,
231let's suppose that your Java SDK was installed in the /usr/lib/jvm/java-6-sun-1.6.0.22/ directory,
232then you can use the following command:
233
234::
235
236  $ ./configure --with-java=/usr/lib/jvm/java-6-sun-1.6.0.22/
237
238This assumes that the include/linux and jre/lib/i386/client/ subdirectories exist in
239/usr/lib/jvm/java-6-sun-1.6.0.22/, include/linux contains the jni.h headers file and
240jre/lib/i386/client/ contains the libjvm.so file.
241
242.. note::
243   With Mac OS X you only have to set ``macos`` as the value for the ``--with-java`` option
244   to activate Java support. For example:
245
246   ::
247
248     $ ./configure --with-java=macos
249
250(Optional) JavaScript Support
251^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
252
253If you want to activate JavaScript support for the ZOO Kernel then you will have to use
254the ``--with-js`` option. If you are using a "Debian-like" GNU/Linux distribution then
255dpkg will be used to detect if the required packages are installed and you don't have to
256specify anything here, so you can use the following command:
257
258::
259
260  $ ./configure --with-js
261
262This assumes that js_api.h and libmozjs.so are found in default directories.
263
264If you have a custom installation of SpiderMonkey or you are not using a Debian packaging
265system, then you'll have to specify the directory where you installed it. For
266instance, let's suppose that you installed your SpiderMonkey in /usr, then you'll
267have to use the following command:
268
269::
270
271  $ ./configure --with-js=/usr
272
273This assumes that the /usr/include/js exists and contains the js_api.h headers file and
274/usr/lib contains libmozjs.so file.
275
276.. _win32:   
277
278OpenSUSE
279********
280
281Zoo-Kernel is maintained as a package in `OpenSUSE Build Service (OBS) <https://build.opensuse.org/package/show?package=zoo-kernel&project=Application%3AGeo>`__.
282This way, rpm's are provided for all versions of openSUSE Linux (11.2, 11.3, 11.4, Factory).
283
284Stable Releases
285^^^^^^^^^^^^^^^
286
287For installing Zoo-Kernel in openSUSE there are 3 ways available:
288
289One Click Installer
290###################
291
292One-click installer that can be found  `here <http://software.opensuse.org/search?q=zoo-kernel&baseproject=openSUSE%3A11.4&lang=en&exclude_debug=true>`__.
293For openSUSE 11.4 this is the direct `link <http://software.opensuse.org/ymp/Application:Geo/openSUSE_11.4/zoo-kernel.ymp?base=openSUSE%3A11.4&query=zoo-kernel>`__.
294
295Yast Software Manager using a GUI
296#################################
297
298The `Application:Geo <http://download.opensuse.org/repositories/Application:/Geo/>`__ repository has to be added
299to the Software Repositories and then Zoo-kernel can be found in Software Management through search.
300
301Command line (as root for openSUSE 11.4)
302########################################
303
304::
305
306  zypper ar http://download.opensuse.org/repositories/Application:/Geo/openSUSE_11.4/
307  zypper refresh
308  zypper install zoo-kernel
309
310Unstable Version
311^^^^^^^^^^^^^^^^
312
313The latest development version of ZOO-Kernel can be found in OBS under the project `home:tzotsos <https://build.opensuse.org/project/show?project=home%3Atzotsos>`__.
314ZOO-Kernel packages are maintained and tested there before being released to the Application:Geo repository.
315
316Installation methods are identical as the stable version. Make sure to use `this <http://download.opensuse.org/repositories/home:/tzotsos/>`__ repository instead.
317
318Command line installation (as root for openSUSE 11.4)
319#####################################################
320
321::
322
323  zypper ar http://download.opensuse.org/repositories/home:/tzotsos/openSUSE_11.4/
324  zypper refresh
325  zypper install zoo-kernel
326  zypper install zoo-kernel-grass-bridge
327
328Additionally, there is the option of adding the zoo-wps-grass-bridge package. This option will automatically install grass7 (svn trunk).
329
330Try the Installation
331^^^^^^^^^^^^^^^^^^^^
332
333- http://localhost/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=GetCapabilities&Version=1.0.0
334- http://localhost/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=DescribeProcess&Version=1.0.0&Identifier=HelloPy
335- http://localhost/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=Execute&Version=1.0.0&Identifier=HelloPy&DataInputs=a=myname
336
337CentOS
338******
339
340.. note::
341   This documentation was created thanks to Guillaume Sueur from Neogeo Technologies which took time to test
342   installing the ZOO-Kernel on a CentOS 5.5 environment.
343
344Requirements
345^^^^^^^^^^^^
346
347Install some standard tools to be able to run ZOO-Kernel on your platform :
348
349::
350
351  yum install apache2
352  yum install build-essentials
353  yum install gcc-c++
354  yum install zlib-devel
355  yum install libxml2-devel
356  yum install bison
357  yum install openssl
358  yum install python-devel
359  yum install subversion
360
361Compile then install FastCGI library from source
362
363::
364
365  wget http://www.fastcgi.com/dist/fcgi.tar.gz
366  tar xzf fcgi-2.4.0.tar.gz
367  ./configure
368  make
369  make install
370  echo /usr/local/lib >> /etc/ld.so.conf.d/local.conf
371  ldconfig
372
373Compile then install the autoconf tools :
374
375::
376
377  wget http://ftp.gnu.org/gnu/autoconf/autoconf-latest.tar.gz
378  tar xzf autoconf-latest.tar.gz
379  ./configure --prefix=/usr
380  make
381  make install
382
383Compile then install the flex tool :
384
385::
386
387  wget http://downloads.sourceforge.net/project/flex/flex/flex-2.5.35/flex-2.5.35.tar.gz?r=http%3A%2F%2Fflex.sourceforge.net%2F&ts=1292529005&use_mirror=switch
388  tar xzf flex-2.5.35.tar.gz
389  cd flex-2.5.35
390  ./configure --prefix=/usr
391  make
392  make install
393
394Using the curl provided in the CentOS distribution will produce a ZOO-Kernel unable to run any
395Service. Indeed, some segmentation faults occur when trying to run ``Execute`` requests on the ZOO-Kernel,
396compiling the ZOO-Kernel setting ``USE_GDB`` flag in the ``CFLAGS`` of your ``Makefile`` will let you run
397ZOO-Kernel from gdb and be able to get more information on what is going wrong with your ZOO-Kernel.
398Doing this we can figure out that code on `line 173 <http://zoo-project.org/trac/browser/trunk/zoo-kernel/ulinet.c#L173>`__
399and `line 175 <http://zoo-project.org/trac/browser/trunk/zoo-kernel/ulinet.c#L175>`__ have to be commented in the
400``ulinet.c`` file to get a ZOO-Kernel working using the curl available in CentOS (curl version 7.15.5).
401If you don't apply the modification, you will get an error from a gdb session pointing
402segfault in ``Curl_cookie_clearall``.
403
404You can optionally compile then install curl from source :
405
406::
407
408  wget http://curl.haxx.se/download/curl-7.21.3.tar.bz2
409  tar xjf curl-7.21.3.tar.bz2
410  cd curl-7.21.3
411  ./configure --prefix=/usr
412  make
413  make install
414
415Compile then install Python :
416
417::
418 
419  wget http://www.python.org/ftp/python/2.6.6/Python-2.6.6.tar.bz2
420  tar xjf Python-2.6.6.tar.bz2
421  cd Python-2.6.6
422  ./configure
423  make
424  make install
425
426Compile then install your own GDAL library :
427
428::
429
430  wget http://download.osgeo.org/gdal/gdal-1.7.3.tar.gz
431  tar xzf gdal-1.7.3.tar.gz
432  cd gdal-1.7.3
433  ./configure  # add your options here
434  make
435  make install
436
437Install the Sun JAVA SDK into ``/usr/share`` then use the following command to ensure that the ``libjvm.so``
438will be found at runtime from any context.
439
440::
441
442  echo /usr/share/java-1.6.0-openjdk-1.6.0.0/jre/lib/i386/client/ >> /etc/ld.so.conf.d/jvm.conf
443  ldconfig
444
445Compile ZOO-Kernel and ZOO-Services
446^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
447
448Compile then install ZOO-Kernel and your first ZOO-Services.
449
450First of all, compile the cgic library providen in the SVN source tree:
451
452::
453
454  svn co http://svn.zoo-project.org/svn/trunk zoo-project
455  cd zoo-project/thirds/cgic206
456  make
457
458Compile then install ZOO-Kernel.
459
460::
461
462  cd ../../zoo-kernel
463  ./configure --with-java=/usr/share/jdk1.6.0_23/ --with-python
464  make zoo_loader.cgi
465  cp main.cfg /var/www/cgi-bin/
466  cp  zoo_loader.cgi /var/www/cgi-bin/
467
468Compile then deploy your first ZOO-ServicesProviders (simple HelloPy, line 1 and 2, and the OGR base-vect-ops
469ServiceProvider, line 3 to 6):
470
471::
472
473  cp ../zoo-services/hello-py/cgi-env/*.zcfg /var/www/cgi-bin/
474  cp ../zoo-services/hello-py/test_service.py /var/www/cgi-bin/
475  cd ../ogr/base-vect-ops/
476  make
477  cp ./cgi-env/* /var/www/cgi-bin/
478  vi /var/www/cgi-bin/main.cfg --> set your own informations here
479
480To ensure that the ``libjvm.so`` will be found from apache, please restart it :
481
482::
483
484  /etc/init.d/httpd restart
485
486Testing your ZOO-Kernel
487^^^^^^^^^^^^^^^^^^^^^^^
488
489Test your ZOO-Kernel from command line:
490
491::
492
493  cd /var/www/cgi-bin
494  ./zoo_loader.cgi "request=Execute&service=WPS&version=1.0.0&Identifier=HelloPy&DataInputs=a=Djay"
495  ./zoo_loader.cgi "request=Execute&service=WPS&version=1.0.0&Identifier=Buffer&DataInputs=BufferDistance=1@datat
496
497Debian / Ubuntu
498***************
499
500.. note::
501   An Ubuntu 10.4 with ZOO virtual image is available at http://www.zoo-project.org/Ubuntu10.4_ZOO.zip
502   (root: ZOO.test)
503
504The following instructions were tested on Debian Squeeze, Ubuntu 10.04 and Ubuntu 10.10
505
506Installation Workflow
507^^^^^^^^^^^^^^^^^^^^^
508
509- install some dependencies
510::
511
512  sudo apt-get install flex bison libfcgi-dev libxml2 libxml2-dev curl openssl autoconf checkinstall
513
514- download ZOO  source
515
516::
517
518  svn checkout http://svn.zoo-project.org/svn/trunk zoo-project
519
520- install cgic from packages
521
522::
523
524  cd zoo-project/thirds/cgic206/
525
526- change the path of installation
527
528::
529
530  nano Makefile
531    - LIBS=-L./ -lcgic ../fcgi-2.4.0/libfcgi/.libs/libfcgi.a --> LIBS=/path/to/libfcgi.a
532    - cp libcgic.a  ../../dist/lib --> cp libcgic.a /usr/lib
533    - cp cgic.h  ../../dist//include --> cp cgic.h  /usr/include
534    - @echo libcgic.a is in  ../../dist/lib and cgic.h is in  ../../dist//include. --> @echo libcgic.a is in  /usr/lib and cgic.h is in /usr/include.
535
536- compile
537
538::
539
540  make
541
542- install
543
544::
545
546  sudo make install
547
548- go to kernel path
549
550::
551
552  cd ../../zoo-kernel/
553
554- create configure file
555
556::
557
558  autoconf
559
560- run configure
561
562.. note::
563   In Ubuntu 10.04 libmozjs-dev does not exist, so to use JS you can compile `SpiderMonkey <https://developer.mozilla.org/en/SpiderMonkey>`__ or use the xulrunner-dev package
564   which includes SpiderMonkey. 
565   For PHP, you must make sure to compile PHP with `--enable-embed <http://www.zoo-project.org/trac/wiki/ZooKernel/Embed/PHP#ConfigureandInstallPHPEmbedlibrary>`__.
566
567::
568
569  ./configure --with-java=/path/to/java
570 
571  to JavaScript with XulRunner SpiderMonkey you have to edit configure file.
572    - JS_CPPFLAGS="-I$JSHOME/include/js" --> JS_CPPFLAGS="-I$JSHOME/include"
573    - JS_LDFLAGS="-L$JSHOME/lib -ljs -lm" --> JS_LDFLAGS="-L$JSHOME/lib -lmozjs -lm"
574    - JS_LIB="js" --> JS_LIB="mozjs"
575   
576  ./configure --with-js=/usr/lib/xulrunner-devel.1.9.2.n
577
578- compile
579
580::
581
582  make zoo_loader.cgi
583
584- copy necessary files into your cgi-bin
585
586::
587
588  sudo cp main.cfg /usr/lib/cgi-bin
589  sudo cp zoo_loader.cgi /usr/lib/cgi-bin
590
591- Install ZOO ServiceProvider
592
593::
594
595  sudo cp ../zoo-services/hello-py/cgi-env/*.zcfg /usr/lib/cgi-bin
596  sudo cp ../zoo-services/hello-py/*.py /usr/lib/cgi-bin/
597
598- change some paths in the main.cfg
599
600::
601
602  sudo nano /usr/lib/cgi-bin/main.cfg
603    - serverAddress = http://127.0.0.1
604    - providerSite = http://127.0.0.1
605
606
607- try the installation
608
609  - http://127.0.0.1/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=GetCapabilities&Version=1.0.0
610  - http://127.0.0.1/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=DescribeProcess&Version=1.0.0&Identifier=HelloPy
611  - http://127.0.0.1/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=Execute&Version=1.0.0&Identifier=HelloPy&DataInputs=a=myname
612
613.. note::
614   If you have some problem in the execute request, add the following to ``main.cfg``:
615
616   ::
617   
618     [env]
619     PYTHONPATH=<YOUR_PYTHONPATH>
620
621WIN32
622-----
623
624To be written soon ...
625
626
Note: See TracBrowser for help on using the repository browser.

Search

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png