INSTALL

------------------------------------------------------------------------

 This software is named soap_proxy, and is intended to be used together
 with EOxServer <http://eoxserver.org>.

 Copyright (C) 2011 ANF DATA spol. s r.o., Prague.
 Author: Milan Novacek

 This file is part of soap_proxy, available from the EOxServer repository
 <http://eoxserver.org>.

Soap_proxy is free software: you can redistribute it and/or modify
it under the EOxServer-SoapProxy Open License.
See the file LICENSE for the full license terms and conditions.

SOAP_PROXY IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

------------------------------------------------------------------------

###############################################
# Quick installation guide for the impatient: #
###############################################

The installation for eoxserer under CentOS is done via rpm.

Prerequisite: eoxserver installed and configured.

Rpms are obtained from 'packages.eox.at'
The rpms are intended for CentOS.

As root:
  rpm -i axis2c_eo-1.6.0-3.x86_64.rpm
  rpm -i eo_soap_proxy-1.0.0-1.x86_64.rpm
  /etc/init.d/httpd restart


###############################################
# Old installation without rpms - quick guide #
###############################################                                                                                                                                              

Caution:  some of this information is dated.
See the rpm specs for the most up to date steps
on what config files to customize and how.

rpm specs are in eoxserver/rpmsrc

------------------------------------
 
1. Install and configure axis2/c.
   Download from
     http://ws.apache.org/axis2/c/download.cgi

   cd someplace
   mkdir axis2c
   setenv AXIS2C_HOME /path/to/someplace/axis2c

   # Follow the instructions in 'doc' to compile- but
   # use something like the following configure line to get the
   #  mod_axis2 configured for compiling at the same time:

   ./configure --with-apache2="/usr/include/apache2" \
     --with-apr="/usr/include/apr-1" --prefix=${AXIS2C_HOME}
   make
   make install

   Copy lib/libmod_axis2.so.0.6.0  to "<apache2 modules directory>" 
   as mod_axis2.so

   Edit the file '${AXIS2C_HOME}/axis2.xml' and ensure that the parameter
   enableMTOM has the value true.

   Check that the following dir exits, if not create it:
   ${AXIS2C_HOME}/services

   Configure mod_axis2 in the apache server config files - see the 
   corresponding section in the detailed instructions below.

   Restart the webserver and open the following page:
     http://127.0.0.1/sp_axis/services
   You should get a page that says "Deployed Services" and is otherwise blank.

2. Configure and Compile Soap Proxy:

   cd <...>/soap_proxy/service

   In 'soapProxy.wsdl' set '<soap:address location=.../>'.
   Copy TEMPLATE_services.xml to ``services.xml``.
   In 'service/services.xml' set 'BackendURL' to the address of eoxserver.

   cd ../src
    -->  in Makefile or in your environment set AXIS2C_HOME appropriately.
    make inst

   Check that 
     http://127.0.0.1/sp_axis/services
   shows the four operations (three WCS operations and GetMsVersion).

3. Optionally run tests described in testing/README.txt.

###############################################
# Installation guide:                         #
###############################################

Contents
=========
    0. Mapserver
    A - General instuctions e.g. for Suse
      A1. Download / {compile?} /  install axis2/c.
      A2. Configure and Compile Soap Proxy
    B - Non-rpm instructions for CentOS
    C -  Test the installation


0. Mapserver
============
A running mapserver with the wcs-1.1_post patch is a prerequisite for
running the service.


**************************************************
A - General instuctions e.g. for (Open)Suse / SLES
***************************************************

A1. Download / {compile?} /  install axis2/c.
============================================

   http://ws.apache.org/axis2/c/download.cgi

On a 32-bit machine the binary distribution is probably ok, no
compilation required.

On a 64-bit machine you need to download the source and compile.
Note: if using a 32-bit httpd2 server, then the 32-bit binary distribution
should be ok - just make sure to use -m32 when compiling the o3s prototype
code.

Download the source dist.

It is recommended to create the required directories (below) as a regular
user (i.e. not root).
Make a directory to install to:
  cd someplace
  mkdir axis2c
  setenv AXIS2C_HOME <...>/someplace/axis2c

Follow the instructions in 'doc' to compile- but
use something like the following configure line to get the mod_axis2
configured for compiling at the same time:

./configure --with-apache2="/usr/include/apache2" \
   --with-apr="/usr/include/apr-1" --prefix=${AXIS2C_HOME}
make
make install

Copy lib/libmod_axis2.so.0.6.0  to "<apache2 modules directory>" 
as mod_axis2.so
The following are possible locations of "<apache2 modules directory>":
OpenSUSE: /lib64/apache2
CentOS:   /etc/httpd/modules

Edit the file '${AXIS2C_HOME}/axis2.xml' and ensure that the parameter
enableMTOM has the value true.

Check that the following dir exits, if not create it:
  ${AXIS2C_HOME}/services

Optional hello service:
-----------------------
  This step should not be required unless you are debugging the
  installation. You can install the 'hello' service from the distribution.
  See the downloaded axis2 documentation for details.


Configure mod_axis2 in the apache server config files.
------------------------------------------------------
NOTE:  set paths below as appropriate for your system. 
       In particular, Axis2RepoPath is AXIS2C_HOME from above.
Edit
 /etc/apache2/default-server.conf
    1. add:
        LoadModule axis2_module  /lib64/apache2/mod_axis2.so
        <IfModule mod_axis2.c>
          Axis2RepoPath /home/xxx/yyy/axis2c
          Axis2LogFile /zzz/yyy/ax2logs
          Axis2MaxLogFileSize 204800
          Axis2LogLevel debug
          <Location /sp_axis>
            SetHandler axis2_module
          </Location>
        </IfModule>


    2. If you are using BackendURL (see 'Configure the soapProxy service'
       below) to invoke mapserver: In the configuration file for apache httpd
       on the target system (this it the machine/address where the URL points
       to), add the following SetEnvIf directive to the block for
       <Directory "/srv/www/cgi-bin">:
         SetEnvIf MS_MAPFILE ^([/\w+-=~#\.]*) MS_MAPFILE=$1

       This only applies for executing mapserver. When the target system
       executues mapserver via its cgi interface, this directive is required to
       set the MS_MAPFILE environment variable to the mapfile location as
       configured by the 'MapFile' parameter in 'services.xml' on the source
       machine.
.

NOTE 2: In theory one should use <IfModule mod_axis2> .. </IfModule>

Also set a proxy for the service, in the same file:
    <IfModule mod_proxy.c>
       ProxyRequests Off
       ProxyPass         /sp_wcs http://127.0.0.1/sp_axis/services/soapProxy
     ...

First check the syntax of the config files:
    httpd2 -t
To restart it may suffice to send USR1 to the parent httpd process.

NOTE for SUSE linux:
  Instead of the LoadModule line, you can also edit the file 
   /etc/sysconfig/apache2 to add axis2 to APACHE_MODULES.

  In this case we cannot just send the USR1 signal to the httpd process,
  because the /etc/sysconfig/apache2 file is parsed into httpd conf files
  only by running /etc/init.d/apache2.  The restart procedure is then:
    httpd2 -t
    /etc/init.d/apache2 restart


Test the installation:
----------------------

  Open a browser to the page http://127.0.0.1/sp_axis/services.
You should get a page that says "Deployed Services".  Unless you
performed the optional installation of the 'hello' service, there should
not be any further details listed.


A2. Configure and Compile Soap Proxy
====================================

 a. Configure the soapProxy service
 ----------------------------------

 cd service
  <edit> the file soapProxy.wsdl:
     At the bottom of the file, set '<soap:address location=.../>' 

  <edit> services.xml:
     Set correct paths for the parameters 'MapFile' and one of
       'MapServ' or 'BackendURL'.
     
     The parameters BackendURL, MapFile, and MapServ are used to configure
     soap_proxy.  They may be defined globally in ../../axis2.xml instead of
     here. MapFile and one of BackendURL or MapServ are required to be
     correctly configured.  If BackendURL is defined, then MapServ is ignored.
     This means if you wish to use MapServ you must delete or comment out the
     BackendURL parameter.
 

 b. Configure the development environment, compile and install
 -------------------------------------------------------------

 cd src
 <edit> Makefile:
    set AXIS2C_HOME appropriately

 make inst


If all went well this should install everything for the soapProxy service in
  ${AXIS2C_HOME}/services


**************************************************
B - Non-rpm instructions for CentOS
***************************************************


Soap_proxy

Installation instructions for CentOS
-----------------------------------

#!/bin/bash
# Assume that a plain cd command takes us to the home directory where
# we wish to install everything, and also $HOME is set to this home dir.

# Prerequisites:
#  mapserver/eoxserver installed
#  httpd-devel package installed (yum install httpd-devel)

###################################################
# get, install and configure  axis2c distribution
####################################################

sudo mkdir /usr/local/share/axis2c

export AXIS2C_HOME=/usr/local/share/axis2c

# Please see http://ws.apache.org/axis2/c/download.cgi to determine
# what to download here.  An example of what this might be is:
wget http://tweedo.com/mirror/apache//ws/axis2/c/1_6_0/axis2c-src-1.6.0.tar.gz

cd
mkdir axis2
cd axis2
gunzip axis2c-src-1.6.0.tar.gz
tar -xf axis2c-src-1.6.0.tar

# compile
cd 
cd axis2/axis2c-src-1.6.0
./configure --with-apache2="/usr/include/httpd" \
--with-apr="/usr/include/apr-1" --prefix=${AXIS2C_HOME}
make
sudo make install

# install into apache area: Copy lib/libmod_axis2.so.0.6.0  to
#  "<apache2 modules directory>"  as mod_axis2.so
# Possible locations of "<apache2 modules directory>" are:
# OpenSuse: /etc/apache2/default-server.conf
# CentOs:   /etc/httpd/modules

sudo cp ${AXIS2C_HOME}/lib/libmod_axis2.so.0.6.0 /etc/httpd/modules/mod_axis2.so

# Edit the file '${AXIS2C_HOME}/axis2.xml' and ensure that the parameter
#   enableMTOM has the value true, and is not commented out.
sudo vi ${AXIS2C_HOME}/axis2.xml

# Check that the following dir exits, and is writeable by the <soapproxy user>,
#  and readable by all. 
# In our example the <soapproxy user> is  'soapprox'
sudo mkdir -p ${AXIS2C_HOME}/services
sudo chown soapprox: ${AXIS2C_HOME}/services
chmod og+r ${AXIS2C_HOME}/services

# Create a log direrectory, owned by httpd's user
sudo mkdir /var/log/axis2
sudo chown <httpd_user>: /var/log/axis2

# on some systems (eg. RedHad based systems using SELinux, such as CentOS)
# it is necessary to run ldconfig and also set the security context with
#  semanage (once all is installed)
sudo echo /usr/local/share/axis2c  >/etc/ld.so.conf.d/axis2c-x86_64.conf
sudo ldconfig /usr/local/share/axis2c/lib

# working with semanage (selinux) :
#  list security context for *.so.*:
#    ls -lZ *.so.*
#
# change a context for a lib file (use full pathname):
# semanage fcontext -a -t lib_t \
#  /usr/share/axis2c_eo/modules/logging/libaxis2_mod_log.so.0.6.0
# or use a wildcard for a directory and all its contents:
#   "/web(/.*)?"

# Configure mod_axis2 in the apache server config files
# NOTE: set paths below as appropriate for your system. 
#       In particular, Axis2RepoPath is AXIS2C_HOME from above.
#
#  make sure apache httpd is confibured to load the Proxy module.
#
sudo cat >/etc/httpd/conf.d/030_axis2c.conf
LoadModule axis2_module /etc/httpd/modules/mod_axis2.so
<IfModule mod_axis2.c>
  Axis2RepoPath /usr/local/share/axis2c
  Axis2LogFile /var/log/axis2/axis2.log
  Axis2MaxLogFileSize 204800
  Axis2LogLevel info
  <Location /sp_axis>
    SetHandler axis2_module
  </Location>
</IfModule>

<IfModule mod_proxy.c>
  ProxyPass         /sp_eowcs http://127.0.0.1/sp_axis/services/soapProxy
  ProxyPassReverse  /sp_eowcs http://127.0.0.1/sp_axis/services/soapProxy
</IfModule>

^D


###############################
# get soap_proxy distibution
###############################
#
cd
mkdir soap_proxy
cd soap_proxy
svn co  http://eoxserver.org/svn/trunk/soap_proxy .


###############################################
# configure and compile  soap_proxy distibution
###############################################
#
# In the directory 'service', Copy TEMPLATE_services.xml to services.xml,
#  then in services.xml set 'BackendURL' to the address of eoxserver and
#  set 'DeleteNonSoapURLs' to true  (needed for the testsuite to see expected
# results).
cd service
cp TEMPLATE_services.xml services.xml
sed -i -e '/name="BackendURL"/c \    <parameter name="BackendURL">http://eoxserver</parameter>' services.xml
sed -i -e 's/name="DeleteNonSoapURLs">false/name="DeleteNonSoapURLs">true/' services.xml

# DEBUG note:
#  for debugging add the following to services.xml:
#   <parameter name="DebugSoapProxy">true</parameter>

# Edit soapProxy.wsdl:
# At the bottom of the file, set '<soap:address location=.../>'
sed -i -e '/soap:address location=/c \           <soap:address location="http://176.9.245.37/sp_eowcs"/>' soapProxy.wsdl

cd ../src
make inst

# set up the loader paths and security context if needed
sudo echo /usr/local/share/axis2c/services/soapProxy/ >>/etc/ld.so.conf.d/axis2c-x86_64.conf
sudo ldconfig /usr/local/share/axis2c/services/soapProxy
sudo semanage fcontext -a -t lib_t /usr/local/share/axis2c/services/soapProxy/libsoapProxy.so
sudo restorecon -v /usr/local/share/axis2c/services/soapProxy/libsoapProxy.so


#################################################
#  Perform basic verification of the installation
#################################################
#  Open a browser to the page http://<server_address>/sp_axis/services.
# You should get the page with "Deployed Services", and soapProxy listing
# the four operations (three WCS operations and GetMsVersion).
#
# Open the page http://<server_address>/sp_eowcs?wsdl
#  and verify you can see the wsdl definition.
#


**************************************************
C - Test the installation
**************************************************

 C1. Check the Service is up and running
 ---------------------------------------
  Open a browser to the page http://127.0.0.1/sp_axis/services.
You should get the page with "Deployed Services", and soapProxy listed
as providing the four operations (three WCS operations and GetMsVersion).

See if you can access the wsdl for the service via a browser:
Open the page http://127.0.0.1/sp_eowcs?wsdl


 C2. Testing with SOAPUI
 -----------------------

See test/README.txt for testing instructions.