=======================
Installing OSAAS Server
=======================

The OSAAS server is the core component of OSAAS.  It accepts HTTP requests from
OSAAS clients containing information about WMS requests, processes the
information and stores it into a database. This chapter will lead you through
OSAAS installation process.


Requirements
------------

Before you are able to install *OSAAS*, you need to install some software:

- Python >= 2.3 (see http://python.org/)

Depending on which database you use, you need one of the following database API
modules:

- cx_Oracle >= 4.3.1 (see http://www.python.net/crew/atuining/cx_Oracle/)
- psycopg2 >= 2.0.5.1 (see http://www.initd.org/pub/software/psycopg/)

After downloading and installing the required software, you should download
*OSAAS* from `wald.intevation.org <http://wald.intevation.org/frs/?group_id=33&release_id=158/>`_
or using *Subversion* (see http://svnbook.red-bean.com/) with the following
command::

  svn checkout https://svn.wald.intevation.org/svn/osaas/trunk osaas-trunk

.. note::

   The recommended way of getting *OSAAS* is to download the tarball of an
   official release instead of checking out the development branch via SVN.

PostgreSQL Configuration
------------------------

The next step is to set up your PostgreSQL database. If you have installed
PostgreSQL from Debian packages, the path definitions of the next steps should
go with your environment. Otherwise, the pathes may differ.

At first, you should create a user *osaas* and the database *osaas_logging* with
the commands below::

  su postgres -c "createuser -SDRleP osaas"
  su postgres -c "createdb -O osaas osaas_logging"

In order that the created user is allowed to access the database, it is
necessary to modify ``/var/lib/pgsql/data/pg_hba.conf`` and ``/var/lib/pgsql/data/postgresql.conf``.

In ``/var/lib/pgsql/data/postgresql.conf`` you will find the config options
*listen_adress* and *port*. Modify these as follows::

  listen_addresses='localhost'
  port = 5432

and append the following line to ``/var/lib/pgsql/data/pg_hba.conf``::

  host osaas_logging osaas  127.0.0.1/32 md5

Now, the PostgreSQL database is ready. Restart it with the command::

  /etc/init.d/postgresql restart


.. _installation-label:

OSAAS Server Installation
-------------------------

*OSAAS* server is written in python and needs no explicit installation.
Downloading the tarball from `wald.intevation.org <http://wald.intevation.org/frs/?group_id=33&release_id=158/>`_
or via SVN is all you need to do. But there are some things you need to
initialize before you are able to run *OSAAS*.

First of all: *OSAAS* server requires a user authentication. Use the
``adduser.py`` script to create new users. The following command will create a
new user *osaas* and ask you for a password for this user. Afterwards, the user
and its hashed password are stored in the user database file given with the -f
option. In this case, users and passwords are stored in *my-osaas-users*::

  ./server/adduser.py -f my-osaas-users osaas

*OSAAS* itself reads a configuration file that contains the database connection
parameters, server settings and information about *OSAAS* datamodel.
``server/demo-config.xml`` is a demo configuration. See `Configuration`_ for
more details on possible configuration options.

After creating a new user and a configuration file, you are ready to initialize
the database using ``initosaasdb.py``. ``initosaasdb.py`` reads your
configuration and creates all necessary database tables - independent of which
database (Oracle or PostgreSQL) you use. Initialize the database with::

  ./server/initosaasdb.py --config-file=my-osaas-config.xml

If everything was fine, you can start *OSAAS* server (see
:ref:`Start\/Stop OSAAS Server <running-label>`).


=============
Configuration
=============

As already mentioned above, you can find a demo configuration in
``server/demo-config.xml``. To understand the config options, please read the
comments inline this configuration::

    <?xml version="1.0"?>
    <OSAASConfig>
      <!-- The port the server will listen on -->
      <Port>8989</Port>

      <!-- The files the server will log to.  The access log holds the usual
           HTTP server access log information.  The error log is used to log
           errors and debug information.  If no file is specified, the
           logging output is written to stderr.

           Supported log levels in order of increasing Verbosity: 
               CRITICAL, ERROR, WARNING, INFO, DEBUG
           Default log level is INFO.
        -->
      <AccessLog>/var/log/osaas/osaas-access.log</AccessLog>
      <ErrorLog>/var/log/osaas/osaas-error.log</ErrorLog>
      <LogLevel>INFO</LogLevel>

      <!-- The users database file. -->
      <UserDB>/etc/osaas/osaas-users</UserDB>

      <!-- File in which to write the PID.  Useful for /etc/init.d scripts -->
      <PidFile>/var/run/osaas.pid</PidFile>

      <!-- The database connection parameters -->
      <DBConnection>
        <!-- Type of the database.  Possible values: oracle, postgresql -->
        <Type>postgresql</Type>

        <!-- Connection parameters as a single string.  Use this for postgresql. -->
        <Parameters>user=mydbuser password=mydbpassword host=localhost port=myport dbname=mydb</Parameters>

        <!-- Connection parameters for Oracle.  Make sure Parameters is
         empty or not present at all when using oracle.  The Parameters
         entry takes precedence over the following parameters. -->
        <User>mydbuser</User>
        <Password>mydbpassword</Password>
        <DSN>myDSN</DSN>
      </DBConnection>

      <!-- The database rules.  The rules describe one table and a mapping
           from the values sent to the OSAAS server to the columns in the
           table.  Some of the values are generated by the OSAAS client (the
           WMS server or OWS proxy) and some are taken from the original
           request sent by the WMS client.  All information taken from the
           original WMS request has names in UPPERCASE.  The values
           generated by the OSAAS client have lowercase names.
        -->
      <DBRules>

        <!-- Definition of the MyOWSAccounting table.  The server expects
         this table to have all the columns defined here and an
         additional column called ID with a unique ID generated by a
         sequence called MyOWSAccounting_seq (the name is derived from
         the table name by append "_seq"). -->
        <insert table="MyOWSAccounting">

          <!-- Defines the column wmsidintern of type character varying(100)
           which will hold the wmsidintern value -->
          <value param="wmsidintern" column="wmsidintern"
             type="character varying(100)"/>

          <!-- external wmsid, defined like wmsidintern -->
          <value param="wmsidextern" column="wmsidextern"
             type="character varying(100)"/>

          <!-- the name of the user is stored in the username column -->
          <value param="user" column="username" type="character varying(20)"/>

          <!-- The start and end timestamps -->
          <value param="starttime" column="starttime"
             type="timestamp with time zone"/>
          <value param="endtime" column="endtime" 
             type="timestamp with time zone"/>

          <!-- The values taken from the original WMS request-->
          <value param="SERVICE" column="service" type="character varying(10)"/>
          <value param="REQUEST" column="req" type="character varying(10)"/>
          <value param="BBOX" column="bbox" type="character varying(100)"/>
          <value param="WIDTH" column="width" type="int"/>
          <value param="HEIGHT" column="height" type="int"/>
        </insert>
      </DBRules>
    </OSAASConfig>


=====================
Building OSAAS Client
=====================

OSAAS Java Client is a small library for java programs that want to send data to
the OSAAS server. The build process uses ant. So, you need to make clear that
you have ant installed (http://ant.apache.org/).

Now, if you have ant installed on your machine, you can change to the
``client/java/`` directory and enter the following command::

  ant

The default ant target builds a ``osaas-client.jar`` file in the ``dist/``
subdirectory. Use this file in your client.


Integration in *deegree OWSProxy*
---------------------------------

First of all, you need to download the deegree2 sources in a specific version,
apply the patch ``client/java/owsproxy/owsproxy.diff`` and make *OSAAS* client
available to deegree. After this, you are ready to build *deegree OWSProxy*.
Follow the instructions below:

1. Download the sources using deegree::

    svn co -r 15164 https://svn.wald.intevation.org/svn/deegree/base/trunk deegree-osaas

2. Apply the patch ``client/java/owsproxy/owsproxy.diff``::

    cd deegree-osaas
    patch -p 0 < owsproxy.diff

3. Make the osaas client code available to deegree (``$DIST_HOME_OSAAS_CLIENT``
   is the directory where ``osaas-client.jar`` is located)::

    cd deegree-osaas/lib
    ln -s $DIST_HOME_OSAAS_CLIENT/ osaas

4. Build deegree::

    ant build-lib

Now, you have built *deegree OWSProxy* with *OSAAS* integration. Finally, you
need to configure logging. *OSAAS* logging configuration is read from the same
WEB-INF/web.xml file as the *OWSProxy* configuration. Add the following lines to
this file and replace the url, username, password and faillog::

    <!-- The URL to which the OSAAS logging information is to be posted
         Note: The url has to end with a '/'.
    --> 
    <init-param>
       <param-name>OSAAS_URL</param-name>
       <param-value>http://localhost:8989/owsaccounting/</param-value>
    </init-param>

    <!-- The user name and password to use for authentication with the 
         OSASS server --> 
    <init-param>
       <param-name>OSAAS_USERNAME</param-name>
       <param-value>aUser</param-value>
    </init-param>
    <init-param>
       <param-name>OSAAS_PASSWORD</param-name>
       <param-value>secret</param-value>
    </init-param>

    <!-- The file into which failed logging attempts are written --> 
    <init-param>
       <param-name>OSAAS_FAILLOG</param-name>
       <param-value>/usr/share/tomcat/logs/osaas-faillog</param-value>
    </init-param>