\section{Installationguide}

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.

For installing and operating the GNV-system access with {\bf root
rights} is needed.  If other permissions are needed, there will be a
hint 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.}
  \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 --
    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 project.

\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:

\verb+ apt-get install sun-java6-jdk+


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

This step is optional but recommended.

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 Artefact 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, 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_12"
  Java(TM) SE Runtime Environment (build 1.6.0_12-b04)
  Java HotSpot(TM) Server VM (build 11.2-b01, mixed mode)
\end{lstlisting}


\subsubsection*{Uninstalling}

For removing Sun Java from the operating system, use:

\verb+apt-get --purge remove sun-java6-jdk+


\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_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.

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.

\subsubsection*{Uninstalling Apache Tomcat}

To uninstall the Apache Tomcat, use the following:
\verb+ apt-get --purge remove tomcat5.5+


\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+:


\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/apache 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.

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 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+ wget http://localhost/gnv/ -O test+

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


\subsubsection*{Uninstalling the Apache Webserver}
To uninstall the Apache Webserver and its configuration, you can use the
following command:
\verb+ apt-get purge apache2+


\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}

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-wrapper .
\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 > METADATA.

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

\begin{lstlisting}
cd root
wget \
"http://localhost/cgi-bin/gnv-wrapper?service=WMS&request=GetCapabilities&version=1.1.1" \
-O mapserver
\end{lstlisting}

For a sucessful configuration, the response document \verb+ mapserver+
contains a XML document describing the capabilities of the mapserver.


\subsubsection*{Un-installing UMN- Mapserver}

To uninstall the UMN-mapserver without its dependencies, execute the following:

\begin{lstlisting}
cd /usr/lib/cgi-bin
rm -i gnv-wrapper
apt-get purge cgi-mapserv-gp
\end{lstlisting}