Index: trunk/docs/tutorial/environment.txt =================================================================== --- trunk/docs/tutorial/environment.txt (revision 134) +++ trunk/docs/tutorial/environment.txt (revision 134) @@ -0,0 +1,115 @@ +.. _environment: + +Using ZOO from an OSGeoLive virtual machine +=========================================== + +Development Environment Description +----------------------------------- + +`OSGeoLive `__ is a live DVD and virtual machine based on +`Xubuntu `__ that allows you to try a +wide variety of open source geospatial software without installing anything. It is +composed entirely of free software and include ZOO 1.0 this year, for testing purpose. + +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. Using a virtual machine image disk seems to be the simplest way to use +ZOO Kernel and to develop ZOO Services locally, as we can ensure that everything +requested for compile C Services and run Python Services is available and ready to use. +Every ZOO related material and source code have been placed in */home/user/zoows* directory. +We will work inside it during this workshop. As the binary version of ZOO Kernel is +already compiled and stored in */home/user/zoows/sources/zoo-kernel*, you only have to +copy two important files inside the */usr/lib/cgi-bin directory*: *zoo_loader.cgi* +and the *main.cfg* in order to make ZOO Kernel available, using the following commands: + +:: + + sudo cp ~/zoows/sources/zoo-kernel/zoo_loader.cgi /usr/lib/cgi-bin + sudo cp ~/zoows/sources/zoo-kernel/main.cfg /usr/lib/cgi-bin + +Please note that we will talk about ZOO Kernel or zoo_loader.cgi script without any +distinction during this workshop. + +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. Obviously, you are free to add new sections +to the files if you need them for a specific Service. Nevertheless, you have to know +that the env section name is used in a specific way. It lets you define environment +variables that your Service requires during its runtime. For instance, if your Service +requires to access to a X server running on framebuffer, you can add *DISPLAY=:1* line in +your env section to take this specificity into account. + +Please have a look to this file. Three important parameters are commented below: + +serverAddress + The url to access to the ZOO Kernel + +tmpPath + The full path to store temporary files + +tmpUrl + The url path relative to serverAddress to access temporary directory. + +The values of the *main.cfg* file used from the running virtual machine are the following: + +:: + + serverAddress=http://localhost/zoo + tmpPath=/var/www/temp + tmpUrl=../temp/ + +You could have noticed that the *tmpUrl* is a relative url from *serverAddress*, so it must +be a directory. Even if ZOO Kernel can be used with the full url of the zoo_loader.cgi +script, for better readability and fully functional ZOO Kernel, you have to modify the +default Apache configuration in order to be able to use the http://localhost/zoo/ url +directly. + +First, please create a zoo directory in the existing */var/www* which is used by Apache as +the DirectoryIndex. Then, please edit the */etc/apache2/sites-available/default* configuration +file and add the following lines after the Directory block related to */var/www* directory : + +:: + + + Options Indexes FollowSymLinks MultiViews + AllowOverride All + Order allow,deny + allow from all + + +Now create a small *.htaccess* file in the */var/www/zoo* containing the following lines: + +:: + + RewriteEngine on + RewriteRule (.*)/(.*) /cgi-bin/zoo_loader.cgi?metapath=$1 [L,QSA] + RewriteRule (.*) /cgi-bin/zoo_loader.cgi [L,QSA] + +For this last file to be taken into account by Apache, you must activate the rewrite +Apache module by copying a load file as bellow : + +:: + + sudo cp /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled/ + +Now you should be able to access the ZOO Kernel using a simplified by restarting +your Apache Web server : + +:: + + sudo /etc/init.d/apache2 restart + +Two other softwares form the OSGeoLive environment will be used during this workshop. +Geoserver will first be used to provide WFS input data for the ZOO Services we are going +to develop. The Geoserver sample dataset (United States polygons) will be passed to our +service during section 3. So please start the Geoserver using the corresponding launcher +in the Servers folder, as illustrated in the following screenshot : + +OpenLayers library is also available on the OSGeoLive virtual machine image disk, and it +will be used during section 4, for building a simple WPS client application able to query +the newly developed ZOO Services. + +As we planned to use OGR C-API and Python module of the GDAL library, we will need the +corresponding header files, libraries and associated files. Hopefully everything was +already available per default and so ready to use on the OSGeoLive packaging. + Index: trunk/docs/tutorial/index.txt =================================================================== --- trunk/docs/tutorial/index.txt (revision 130) +++ trunk/docs/tutorial/index.txt (revision 134) @@ -4,4 +4,7 @@ ============ - - +.. toctree:: + :maxdepth: 2 + + introduction + environment Index: trunk/docs/tutorial/introduction.txt =================================================================== --- trunk/docs/tutorial/introduction.txt (revision 134) +++ trunk/docs/tutorial/introduction.txt (revision 134) @@ -0,0 +1,97 @@ +.. _tutorialintro: + +Introduction +============ + +What is ZOO? +------------ + +ZOO is a WPS (Web Processing Service) open source project recently released under a MIT/X-11 +style license. It provides an OGC WPS compliant developer-friendly framework to create and +chain WPS Web services. ZOO is made of three parts: + +ZOO Kernel + A powerful server-side C Kernel which makes it possible to manage and chain Web services + coded in different programming languages. + +ZOO Services + A growing suite of example Web Services based on various open source libraries. + +ZOO API + A server-side JavaScript API able to call and chain the ZOO Services, which makes the + development and chaining processes easier. + +ZOO is designed to make the WPS server-side development easier by providing a powerful system +able to understand and execute WPS compliant queries. It supports several programming languages, +thus allowing you to create Web Services in your favorite language and from existing code. +Further information on the project is available on the +`ZOO Project official website `__. + +How does ZOO work? +------------------ + +ZOO is based on a 'WPS Service Kernel' which constitutes the ZOO's core system (aka ZOO Kernel). +The latter is able to load dynamic libraries and to handle them as on-demand Web services. +The ZOO Kernel is written in C language, but supports several common programming languages +for creating ZOO Services. + +A :ref:`ZOO Service ` is a link composed of a ZOO metadata file (.zcfg) and the code +for the corresponding implementation. The metadata file describes all the available functions +which can be called using a WPS Exec Request, as well as the desired input/output. Services +contain the algorithms and functions, and can now be implemented in C/C++, Fortran, Java, +Python, PHP and JavaScript. + +:ref:`ZOO Kernel ` works with Apache and can communicate with cartographic engines +and Web mapping clients. It simply adds the WPS support to your spatial data infrastructure +and your Web mapping application. It can use every GDAL/OGR supported formats as input data +and create suitable vector or raster output for your cartographic engine and/or your +web-mapping client application. + +What are we going to do in this workshop? +----------------------------------------- + +This workshop aims to present the ZOO Project and its features, and to explain its capabilities +regarding the WPS 1.0.0 specification. The participants will learn in 3 hours how to use ZOO +Kernel, how to create ZOO Services and their configuration files and finally how to link +the created Service with a client-side webmapping application. + +A pre-compiled ZOO 1.0 version is provided inside OSGeoLive, the OSGeo official Live DVD. +For the sack of simplicity, an OSGeoLive Virtual Machine image disk is already installed +on your computers. This will be used during this workshop, so the participants won't have +to compile and install ZOO Kernel manually. Running and testing ZOO Kernel from this +OSGeoLive image disk is thus the first step of the workshop, and every participants should +get a working ZOO Kernel in less than 30 minutes. + +Once ZOO Kernel will be tested from a Web browser using GetCapabilities requests, +participants will be invited to create an OGR based ZOO Service Provider aiming to enable +simple spatial operations on vector data. Participants will first have to choose whether +they will create the service using C or Python language. Every programming step of the ZOO +Service Provider and the related Services will be each time detailed in C and Python. + +Once the ZOO Services will be ready and callable by ZOO Kernel, participants will finally +learn how to use its different functions from an OpenLayers simple application. A sample +dataset from Geoserver will be displayed on a simple map using WMS/WFS standards and used as +input data by the ZOO Services. Then, some specific selection and execution controls will be +added in the JavaScript code in order to execute single and multiple geometries on the displayed +polygons. + +Once again, the whole procedure will be organized step-by-step and detailed with numerous code +snippets and their respective explanations. The instructors will check the ZOO Kernel functioning +on each machine and will assist you while coding. Technical questions are of course welcome +during the workshop. + +Usefull tips for reading +------------------------ + +Codes snipets are included in yellow blocks + +Code changes are included in grey blocks + +Code snipets included in sentences are displayed this way + +HTTP and XML Requests are included in blue blocks + + + +*Let's go !* +