--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/admin-manual/installation-base.tex	Fri Sep 28 12:13:58 2012 +0200
@@ -0,0 +1,331 @@
+\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{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\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_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}
+
+
+\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\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/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\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 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}
+
+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 .
+\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.
+
+\subsubsection*{Test of installation}
+Check for a sucessful installation via:
+
+\begin{lstlisting}
+cd root
+curl \
+"http://localhost/cgi-bin/gnv-wms?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.