\section{Installation and Configuration}

This section describes preconditions for the entire system and an installation
on a Debian 5.0.x (Lenny) for the GNV-System without an running X-Environment.
Mostly, the debian package management\footnote{Further information at
\url{http://www.debian.org/doc/manuals/debian-reference/ch02.en.html}}
using \verb+ aptitude+ is used in this manual.

If existing configurations have to be changed, the following notation will be
used: \verb|+| for adding a line replacing the marked by \verb|-|.

\subsection{Preconditions}

\subsubsection*{System}

\begin{itemize}
  \item Storage for the delivered software: 100 MB
  \item Current processor on a 32-bit Architecture (Beginning
    2010)\footnote{Running on a 64-bit system should work out of the box
    and improve scalibility issues (not tested yet).}
  \item RAM: 1 GB for production as minimum.\footnote{This value depends
    mainly on the amount of connected users.}
  \item Network access to Database Backend
  \item RW-Access to the filesystem for logging, shapefile-export,
    caching
\end{itemize}

\subsubsection*{Database: Software and Data}

The software has been developed for the following system:

\begin{itemize}
  \item ESRI ArcSDE 9.3.1 on Oracle 10.2\footnote{The development
    started in ESRI ArcSDE 9.2. There are known
    problems with this version.}
  \item ArcMarineBSH, model package "Time Series and Measurements"
  \item ArcMarineBSH, model package " MeshFeature"
  \item ArcMarineBSH, model package "Marine Feature"
  \item ArcS57 -- International Hydrographic Organization (IHO) S-57 for
    ENC Data Model. - ESRI Data Models. http://support.esri.com/datamodels
  \item CONTIS -- Federal Maritime and Hydrographic Agency (BSH). Continental 
    Shelf Information System -- \\
    \url{http://www.bsh.de/en/Marine\_uses/Industry/CONTIS\_maps/index.jsp}
  \item GNV specific schema MapViewer interface -- Schema for integrating with MapViewer and
    their WMS services
  \item GNV specific schema for managing the cache -- The central
    dataware house is updated regulary. To keep the cache up-to-date,
    needs to cleaned after database updates.
\end{itemize}


\subsection{Operating System}

{\em Hint}: Configuring of partitions, firewalls, etc. for the system is out of
the scope of this documentation.

\subsection{Preparations}

In some steps it is required to use templates wich are packed in
\verb+ artifact-server-$VERSION.tar.bz2+ to get access to those files.

Please extract the tar.bz2 file as explained in 
Chapter~\ref{ref:artifact-server-install},
 p.~\pageref{ref:artifact-server-install}.

The complete document use the system-variable \verb+$ARTIFACT_SERVER_HOME+
to refer the root-directory of the Artifac-Server.
It might be helpful to export this variable using the following command:

\verb+ export ARTIFACT_SERVER_HOME=/opt/artifact-server+ 

\subsection{Java Environment}

\subsubsection*{Installation Sun Java 6}

This GNV-system is developed for Sun Java 6. 

Add non-free packages of the Debian distribution to the system in
\verb+/etc/apt/sources.list+:

\begin{lstlisting}
  [...]
  deb http://ftp.de.debian.org/debian/ lenny main non-free
  deb-src http://ftp.de.debian.org/debian/ lenny main

  deb http://security.debian.org/ lenny/updates main
  deb-src http://security.debian.org/ lenny/updates main
  [...]
\end{lstlisting}


Install Sun Java 6 and its dependencies by executing the following:

\begin{lstlisting}
   apt-get update
   apt-get install sun-java6-jdk
\end{lstlisting}

\subsubsection*{Install Native Components for Java6 (optional)}

This step is optional but recommended\footnote{For background
information, c.f. \url{http://tomcat.apache.org/tomcat-5.5-doc/apr.html}}.

For a better support of the native server technologies, the package
\verb+libtcnative+ can be installed.

\begin{lstlisting}
  apt-get install libtcnative-1
  cd /usr/lib/jvm/java-6-sun/jre/lib/i386/client
  ln -s /usr/lib/libtcnative-1.so
\end{lstlisting}

\subsubsection*{Configuration}

To ensure that the Apache Tomcat and the GNV Artifact-Server will use
Sun Java 6 exclusively, switch to the default Java version
globally\footnote{This manual assumes that there are no other packages
depending to another Java version.}.

Use  \verb+update-alternatives+ mechanism of the Debian
system\footnote{Background information: {\tt man update-alternatives}}, execute:

\verb+ update-alternatives --list java+

Lists all installed Java-Environments. E.g.:
 
\begin{lstlisting}
  Auswahl      Alternative
  -----------------------------------------------
            1    /usr/bin/gij-4.3
   +        2    /usr/lib/jvm/java-gcj/jre/bin/java
            3    /usr/lib/jvm/java-1.5.0-sun/jre/bin/java
   *        4    /usr/lib/jvm/java-6-sun/jre/bin/java
\end{lstlisting}


\verb+update-alternatives --config java+

Opens a dialog to reconfigure the java version which should be used as default.
Type the Number of the the java which should be used.
For the example above, type "4".

\subsubsection*{Test of the Installation}

Execute \verb+ java -version+

Check if a version of 1.6.0* has been set. Check:

\begin{lstlisting}
  java version  "1.6.0_20-b02"
  Java(TM) SE Runtime Environment (build 1.6.0_20-b02)
  Java HotSpot(TM) Server VM (build 11.2-b01, mixed mode)
\end{lstlisting}


\subsection{Tomcat Application Server}
To run the GNV-System a Apache Tomcat Server Version 5.5 is required.
This section describes the steps for installing and configuring
Apache Tomcat.

\subsubsection*{Installation}

To install the Tomcat Application-Server and its dependencies, execute:

\verb+ apt-get install tomcat5.5+

\subsubsection*{Configuration}

Adapt some run-time specific properties in
\verb+/etc/default/tomcat5.5+:

\begin{lstlisting}
   - #JAVA_HOME="/usr/lib/jvm/java-6-sun/"
   + JAVA_HOME="/usr/lib/jvm/java-6-sun/"
   
   - #JAVA_OPTS="-Djava.awt.headless=true -Xmx128M"
   + JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m -server"

   - #TOMCAT5_SECURITY=yes
   + TOMCAT5_SECURITY=no
\end{lstlisting}

{\bf Hint: As there is no Java security policy for the GNV WebClient,
Java Security Management is switched off.}

The Apache Tomcat is integrate with Apache WebServer just via the Apache
JServ Protocoll (AJP). To secure the connection, just local connections
are allowed for AJP on Tomcat\footnote{For background information, c.f.
\url{http://tomcat.apache.org/tomcat-5.5-doc/connectors.html}}.

Modify the \verb+ /etc/tomcat5.5/server.xml+:
\begin{lstlisting}

    # Deactivate Standard HTTP Connector:

    +<!--
     <Connector port="8180" maxHttpHeaderSize="8192" address="127.0.0.1"
                maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
                enableLookups="false" redirectPort="8443" acceptCount="100"
                connectionTimeout="20000" disableUploadTimeout="true" />
    +-->
 
     - <Connector port="8009" 
     -           enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />
 
     + <Connector port="8009" 
     +           enableLookups="false" redirectPort="8443" protocol="AJP/1.3" address="127.0.0.1"/>
\end{lstlisting}
 
To activate these changes, restart  Apache Tomcat:
 
\verb+ /etc/init.d/tomcat5.5 restart+

 \subsubsection*{Test of the Installation}

Check if the port 8009 is opened via:
\verb+ netstat -nltp | grep 8009+

A possible listing looks like this:
\begin{lstlisting}
  tcp        0      0 127.0.0.1:8009          0.0.0.0:*  LISTEN      19252/jsvc
\end{lstlisting}
 
So fare, there is no commandline client for AJP to test the connection.
If there are problems, setup \verb+ mod_jk+ module in Apache WebServer
and check its according log files.

\subsection{Apache Webserver}
This section describes the required steps for the installation and configuration 
of the Apache Webserver Version 2.2. Apache WebServer controls all
HTTP-Connections to the outside of the system. Apache Tomcat is
integrated via mod\_jk.

\subsubsection*{Installation}

To install the Apache Webserver you have to execute the following command:

\verb+ apt-get install apache2+

To establish the connection between the Tomcat application server and
Apache Webserver an additional Module "mod\_jk" has to be installed.

\verb+ apt-get install libapache2-mod-jk+

\subsubsection*{Configuring mod\_jk}

Edit the settings for mod\_jk in
file \verb+ /etc/libapache2-mod-jk/workers.properties+. For further
information, there are comments in the configuration file\footnote{Background
information can be found at \\
\url{http://tomcat.apache.org/connectors-doc/generic\_howto/workers.html}}.


\begin{lstlisting}
  - workers.java_home= /usr/lib/jvm/java-gcj/
  + workers.java_home=/usr/lib/jvm/java-6-sun
\end{lstlisting}

In file \verb+ /etc/apache2/httpd.conf+:

\begin{lstlisting}
  + JkWorkersFile "/etc/libapache2-mod-jk/workers.properties"
  + JkLogFile "/var/log/mod_jk.log"
\end{lstlisting}

After finishing the configuration, enable the module in Apache
WebServer: \verb+ a2enmod jk+ and restart the server 
\verb+ /etc/init.d/apache2 restart+.


\subsubsection*{Publish the site in Apache WebServer}

Depending of the existing configuration of Apache WebServer, the
following steps can differ. In this case, a vanilla configuration is
assumed\footnote{Background information about Apache WebServer can
be found at \url{http://httpd.apache.org/docs/2.2/}}.

Disable default configuration
\verb+ a2dissite default+

Adapt eMail-address for configuration in 
\verb+ $ARTIFACT_SERVER_HOME/install/debian/apache2/gnv+.

Enable the specific site (VirtualHost) in Apache WebServer:
\begin{lstlisting}
  cp -i $ARTIFACT_SERVER_HOME/install/debian/apache2/gnv to /etc/apache2/sites-available
  # Activate site for GNV
  a2ensite gnv
  /etc/init.d/apache reload
\end{lstlisting}


\subsubsection*{Test of the Installation}

You can test the installation by executing the following url:

\verb+ curl "http://localhost/gnv/" -o test+

After a successful installation, the file {test} will contain HTML describing
the startpage of the GNV WebClient.


\subsection{UMN MapServer: Installation and configuration}
The UMN MapServer is part of the artifact server. It is responsible for
rendering shapefiles produced by the artifact-server and publish them as
OGC Web Map Service.

\subsubsection*{Installation}
It is recommended to use a more recent version than the one in Debian
Lenny. In the installation package, there is a debian package of
MapServer that should be installed.

In order to verify the integrity of the installation package, it is necessary to import 
a GPG-Key which was used to sign the packages:

\begin{lstlisting}
gpg --keyserver hkp://keys.gnupg.net --recv-keys EC70B1B8
gpg --export EC70B1B8 | apt-key add -
\end{lstlisting}

Installing the mapserver-gp and its dependencies, executing the following command:

\begin{lstlisting}
cd $ARTIFACT_SERVER_HOME/install/debian/umn-mapserver
dpkg -i cgi-mapserver-gp_5.6.3-1~gp+1_i386.deb
\end{lstlisting}

If there are libraries which are required by the Mapserver but not
installed yet run the following command:
\begin{lstlisting}
apt-get -f install
\end{lstlisting}


Provide a possibility to integrate Mapserver properly and transfer
configurations to MapServer during runtime:

\begin{lstlisting}
cd /usr/lib/cgi-bin
cp -i $ARTIFACT_SERVER_HOME/install/debian/umn-mapserver/gnv-wms .
chmod +x gnv-wms
\end{lstlisting}

For setting proper contact details in the WMS Capabilities response,
edit the file \verb+ $ARTIFACT_SERVER_HOME/conf/maptemplates/mapfile.vm+
in the section WEB $\rightarrow$ METADATA.

The Mapserver will need fonts for rendering lables in the map.
To provide this it is required to install the freefonts.
\begin{lstlisting}
apt-get install ttf-freefont
\end{lstlisting}


\subsubsection*{Test of installation}
Check for a sucessful installation via:

\begin{lstlisting}
cd root
curl \
"http://localhost/cgi-bin/gnv-wms" \
-o mapserver
\end{lstlisting}

For a sucessful configuration, the response document \verb+ mapserver+
contains a Value which contains the following message of the mapserver.

TODO: QUERYSTRING WAS EMPTY HINZUFUEGEN

\subsection{Proxy-Script: Installation and Configuration}
The Proxy-Script is required to allow the Map-Client to request external
services. Security policies forbit and prevent requesting those services - like
a GetFeatureInfo request - directly.

\subsubsection{Installation}

First make sure that python is installed on the operating system.
Otherwise install python using the following command:

\verb+ apt-get install python+

Then the script itself must be published on the server by executing the
following steps:

\begin{lstlisting}
cd /usr/lib/cgi-bin
cp -i $ARTIFACT_SERVER_HOME/install/debian/ol-proxy/proxy.cgi .
\end{lstlisting}

\subsubsection{Configuration}
The Proxy-Script can only communicate with servers it is allowed to.
To enable the communication to the server where the UMN-Mapserver is hosted
or to other Server it is necessary to edit {\tt allowedHosts} in the
Proxy-Script at line 18.

There you have to replace the placeholder THISHOSTNAME with the name which
will be used to reach the GNV-Web-Client.

You can add further servers using the syntax which is given in the script.

\subsubsection{Test of installation}

It is possible to test the installation using the following command:

\begin{lstlisting}
curl http://localhost/cgi-bin/proxy.cgi?url=http%3A%2F%2Flocalhost/cgi-bin/mapserv-gp
\end{lstlisting}

If localhost is allowed in the proxy-script the result might be this:

\begin{lstlisting}
TODO: QUERYSTRING WAS EMPTY HINZUFUEGEN
\end{lstlisting}