
hans@922: \section{Installation and Configuration}
hans@901: 
hans@924: This section describes preconditions for the entire system and an installation
hans@924: on a Debian 5.0.x (Lenny) for the GNV-System without an running X-Environment.
hans@924: Mostly, the debian package management\footnote{Further information at
hans@924: \url{http://www.debian.org/doc/manuals/debian-reference/ch02.en.html}}
hans@924: using \verb+ aptitude+ is used in this manual.
hans@901: 
hans@924: If existing configurations have to be changed, the following notation will be
hans@924: used: \verb|+| for adding a line replacing the marked by \verb|-|.
hans@901: 
hans@901: \subsection{Preconditions}
hans@901: 
hans@922: \subsubsection*{System}
hans@901: 
hans@901: \begin{itemize}
hans@901:   \item Storage for the delivered software: 100 MB
hans@901:   \item Current processor on a 32-bit Architecture (Beginning
hans@901:     2010)\footnote{Running on a 64-bit system should work out of the box
hans@924:     and improve scalibility issues (not tested yet).}
hans@901:   \item RAM: 1 GB for production as minimum.\footnote{This value depends
hans@901:     mainly on the amount of connected users.}
hans@901:   \item Network access to Database Backend
hans@901:   \item RW-Access to the filesystem for logging, shapefile-export,
hans@901:     caching
hans@901: \end{itemize}
hans@901: 
hans@922: \subsubsection*{Database: Software and Data}
hans@901: 
hans@901: The software has been developed for the following system:
hans@901: 
hans@901: \begin{itemize}
hans@901:   \item ESRI ArcSDE 9.3.1 on Oracle 10.2\footnote{The development
hans@901:     started in ESRI ArcSDE 9.2. There are known
hans@901:     problems with this version.}
hans@901:   \item ArcMarineBSH, model package "Time Series and Measurements"
hans@901:   \item ArcMarineBSH, model package " MeshFeature"
hans@901:   \item ArcMarineBSH, model package "Marine Feature"
hans@901:   \item ArcS57 -- International Hydrographic Organization (IHO) S-57 for
hans@901:     ENC Data Model. - ESRI Data Models. http://support.esri.com/datamodels
hans@901:   \item CONTIS -- Federal Maritime and Hydrographic Agency (BSH). Continental 
hans@924:     Shelf Information System -- \\
hans@922:     \url{http://www.bsh.de/en/Marine\_uses/Industry/CONTIS\_maps/index.jsp}
hans@901:   \item GNV specific schema MapViewer interface -- Schema for integrating with MapViewer and
hans@901:     their WMS services
hans@901:   \item GNV specific schema for managing the cache -- The central
hans@901:     dataware house is updated regulary. To keep the cache up-to-date,
hans@901:     needs to cleaned after database updates.
hans@901: \end{itemize}
hans@901: 
hans@901: 
hans@901: \subsection{Operating System}
hans@901: 
hans@901: {\em Hint}: Configuring of partitions, firewalls, etc. for the system is out of
hans@922: the scope of this documentation.
hans@901: 
hans@901: \subsection{Java Environment}
hans@901: 
hans@901: \subsubsection*{Installation Sun Java 6}
hans@901: 
hans@901: This GNV-system is developed for Sun Java 6. 
hans@901: 
hans@901: Add non-free packages of the Debian distribution to the system in
hans@901: \verb+/etc/apt/sources.list+:
hans@901: 
hans@901: \begin{lstlisting}
hans@901:   [...]
hans@901:   deb http://ftp.de.debian.org/debian/ lenny main non-free
hans@901:   deb-src http://ftp.de.debian.org/debian/ lenny main
hans@901: 
hans@901:   deb http://security.debian.org/ lenny/updates main
hans@901:   deb-src http://security.debian.org/ lenny/updates main
hans@901:   [...]
hans@901: \end{lstlisting}
hans@901: 
hans@901: 
hans@901: Install Sun Java 6 and its dependencies by executing the following:
hans@901: 
hans@901: \verb+ apt-get install sun-java6-jdk+
hans@901: 
hans@901: 
hans@901: \subsubsection*{Install Native Components for Java6 (optional)}
hans@901: 
hans@924: This step is optional but recommended\footnote{For background
hans@924: information, c.f. \url{http://tomcat.apache.org/tomcat-5.5-doc/apr.html}}.
hans@901: 
hans@901: For a better support of the native server technologies, the package
hans@901: \verb+libtcnative+ can be installed.
hans@901: 
hans@921: \begin{lstlisting}
hans@921:   apt-get install libtcnative-1
hans@921:   cd /usr/lib/jvm/java-6-sun/jre/lib/i386/client
hans@921:   ln -s /usr/lib/libtcnative-1.so
hans@921: \end{lstlisting}
hans@901: 
hans@901: \subsubsection*{Configuration}
hans@901: 
hans@922: To ensure that the Apache Tomcat and the GNV Artifact-Server will use
hans@901: Sun Java 6 exclusively, switch to the default Java version
hans@901: globally\footnote{This manual assumes that there are no other packages
hans@901: depending to another Java version.}.
hans@901: 
hans@924: Use  \verb+update-alternatives+ mechanism of the Debian
hans@924: system\footnote{Background information: {\tt man update-alternatives}}, execute:
hans@901: 
hans@901: \verb+ update-alternatives --list java+
hans@901: 
hans@901: Lists all installed Java-Environments. E.g.:
hans@901:  
hans@901: \begin{lstlisting}
hans@901:   Auswahl      Alternative
hans@901:   -----------------------------------------------
hans@901:             1    /usr/bin/gij-4.3
hans@901:    +        2    /usr/lib/jvm/java-gcj/jre/bin/java
hans@901:             3    /usr/lib/jvm/java-1.5.0-sun/jre/bin/java
hans@901:    *        4    /usr/lib/jvm/java-6-sun/jre/bin/java
hans@901: \end{lstlisting}
hans@901: 
hans@901: 
hans@901: \verb+update-alternatives --config java+
hans@901: 
hans@901: Opens a dialog to reconfigure the java version which should be used as default.
hans@901: Type the Number of the the java which should be used.
hans@901: For the example above, type "4".
hans@901: 
hans@901: \subsubsection*{Test of the Installation}
hans@901: 
hans@901: Execute \verb+ java -version+
hans@901: 
hans@901: Check if a version of 1.6.0* has been set. Check:
hans@901: 
hans@901: \begin{lstlisting}
hans@901:   java version  "1.6.0_12"
hans@901:   Java(TM) SE Runtime Environment (build 1.6.0_12-b04)
hans@901:   Java HotSpot(TM) Server VM (build 11.2-b01, mixed mode)
hans@901: \end{lstlisting}
hans@901: 
hans@901: 
hans@901: \subsection{Tomcat Application Server}
hans@901: To run the GNV-System a Apache Tomcat Server Version 5.5 is required.
hans@901: This section describes the steps for installing and configuring
hans@901: Apache Tomcat.
hans@901: 
hans@901: \subsubsection*{Installation}
hans@901: 
hans@901: To install the Tomcat Application-Server and its dependencies, execute:
hans@901: 
hans@901: \verb+ apt-get install tomcat5.5+
hans@901: 
hans@921: \subsubsection*{Configuration}
hans@901: 
hans@901: Adapt some run-time specific properties in
hans@901: \verb+/etc/default/tomcat5.5+:
hans@901: 
hans@901: \begin{lstlisting}
hans@901:    - #JAVA_OPTS="-Djava.awt.headless=true -Xmx128M"
hans@901:    + JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m -server"
hans@901: 
hans@901:    - #TOMCAT5_SECURITY=yes
hans@901:    + TOMCAT5_SECURITY=no
hans@901: \end{lstlisting}
hans@901: 
hans@901: {\bf Hint: As there is no Java security policy for the GNV WebClient,
hans@901: Java Security Management is switched off.}
hans@901: 
hans@901: The Apache Tomcat is integrate with Apache WebServer just via the Apache
hans@901: JServ Protocoll (AJP). To secure the connection, just local connections
hans@924: are allowed for AJP on Tomcat\footnote{For background information, c.f.
hans@924: \url{http://tomcat.apache.org/tomcat-5.5-doc/connectors.html}}.
hans@901: 
hans@901: Modify the \verb+ /etc/tomcat5.5/server.xml+:
hans@901: \begin{lstlisting}
hans@901: 
hans@901:     # Deactivate Standard HTTP Connector:
hans@901: 
hans@901:     +<!--
hans@901:      <Connector port="8180" maxHttpHeaderSize="8192" address="127.0.0.1"
hans@901:                 maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
hans@901:                 enableLookups="false" redirectPort="8443" acceptCount="100"
hans@901:                 connectionTimeout="20000" disableUploadTimeout="true" />
hans@901:     +-->
hans@901:  
hans@901:      - <Connector port="8009" 
hans@901:      -           enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />
hans@901:  
hans@901:      + <Connector port="8009" 
hans@901:      +           enableLookups="false" redirectPort="8443" protocol="AJP/1.3" address="127.0.0.1"/>
hans@901: \end{lstlisting}
hans@901:  
hans@901: To activate these changes, restart  Apache Tomcat:
hans@901:  
hans@901: \verb+ /etc/init.d/tomcat5.5 restart+
hans@901: 
hans@901:  \subsubsection*{Test of the Installation}
hans@901: 
hans@901: Check if the port 8009 is opened via:
hans@901: \verb+ netstat -nltp | grep 8009+
hans@901: 
hans@901: A possible listing looks like this:
hans@901: \begin{lstlisting}
hans@901:   tcp        0      0 127.0.0.1:8009          0.0.0.0:*  LISTEN      19252/jsvc
hans@901: \end{lstlisting}
hans@901:  
hans@901: So fare, there is no commandline client for AJP to test the connection.
hans@901: If there are problems, setup \verb+ mod_jk+ module in Apache WebServer
hans@901: and check its according log files.
hans@901: 
hans@901: \subsection{Apache Webserver}
hans@901: This section describes the required steps for the installation and configuration 
hans@921: of the Apache Webserver Version 2.2. Apache WebServer controls all
hans@921: HTTP-Connections to the outside of the system. Apache Tomcat is
hans@921: integrated via mod\_jk.
hans@901: 
hans@901: \subsubsection*{Installation}
hans@901: 
hans@901: To install the Apache Webserver you have to execute the following command:
hans@901: 
hans@921: \verb+ apt-get install apache2+
hans@901: 
hans@921: To establish the connection between the Tomcat application server and
hans@921: Apache Webserver an additional Module "mod\_jk" has to be installed.
hans@901: 
hans@921: \verb+ apt-get install libapache2-mod-jk+
hans@901: 
hans@921: \subsubsection*{Configuring mod\_jk}
hans@921: 
hans@921: Edit the settings for mod\_jk in
hans@924: file \verb+ /etc/libapache2-mod-jk/workers.properties+. For further
hans@924: information, there are comments in the configuration file\footnote{Background
hans@924: information can be found at \\
hans@924: \url{http://tomcat.apache.org/connectors-doc/generic\_howto/workers.html}}.
hans@921: 
hans@901: 
hans@901: \begin{lstlisting}
hans@901:   - workers.java_home= /usr/lib/jvm/java-gcj/
hans@901:   + workers.java_home=/usr/lib/jvm/java-6-sun
hans@901: \end{lstlisting}
hans@901: 
hans@921: In file \verb+ /etc/apache2/httpd.conf+:
hans@901: 
hans@901: \begin{lstlisting}
hans@901:   + JkWorkersFile "/etc/libapache2-mod-jk/workers.properties"
hans@901:   + JkLogFile "/var/log/mod_jk.log"
hans@901: \end{lstlisting}
hans@901: 
hans@921: After finishing the configuration, enable the module in Apache
hans@921: WebServer: \verb+ a2enmod jk+ and restart the server 
hans@921: \verb+ /etc/init.d/apache restart+.
hans@901: 
hans@901: 
hans@921: \subsubsection*{Publish the site in Apache WebServer}
hans@901: 
hans@921: Depending of the existing configuration of Apache WebServer, the
hans@921: following steps can differ. In this case, a vanilla configuration is
hans@924: assumed\footnote{Background information about Apache WebServer can
hans@924: be found at \url{http://httpd.apache.org/docs/2.2/}}.
hans@901: 
hans@921: Disable default configuration
hans@921: \verb+ a2dissite default+
hans@921: 
hans@921: Adapt eMail-address for configuration in 
hans@921: \verb+ $ARTIFACT_SERVER_HOME/install/debian/apache2/gnv+.
hans@921: 
hans@921: Enable the specific site (VirtualHost) in Apache WebServer:
hans@921: \begin{lstlisting}
hans@921:   cp -i $ARTIFACT_SERVER_HOME/install/debian/apache2 to /etc/apache2/sites-available
hans@921:   # Activate site for GNV
hans@921:   a2ensite gnv
hans@921:   /etc/init.d/apache reload
hans@921: \end{lstlisting}
hans@921: 
hans@901: 
hans@901: \subsubsection*{Test of the Installation}
hans@901: 
hans@921: You can test the installation by executing the following url:
hans@901: 
hans@924: \verb+ curl "http://localhost/gnv/" -o test+
hans@921: 
hans@921: After a successful installation, the file {test} will contain HTML describing
hans@921: the startpage of the GNV WebClient.
hans@901: 
hans@901: 
hans@921: \subsection{UMN MapServer: Installation and configuration}
hans@921: The UMN MapServer is part of the artifact server. It is responsible for
hans@921: rendering shapefiles produced by the artifact-server and publish them as
hans@921: OGC Web Map Service.
hans@901: 
hans@921: \subsubsection*{Installation}
hans@921: It is recommended to use a more recent version than the one in Debian
hans@921: Lenny. In the installation package, there is a debian package of
hans@921: MapServer that should be installed.
hans@901: 
hans@921: In order to verify the integrity of the installation package, it is necessary to import 
hans@921: a GPG-Key which was used to sign the packages:
hans@901: 
hans@901: \begin{lstlisting}
hans@921: gpg --keyserver hkp://keys.gnupg.net --recv-keys EC70B1B8
hans@921: gpg --export EC70B1B8 | apt-key add -
hans@901: \end{lstlisting}
hans@901: 
hans@921: Installing the mapserver-gp and its dependencies, executing the following command:
hans@901: 
hans@901: \begin{lstlisting}
hans@921: cd $ARTIFACT_SERVER_HOME/install/debian/umn-mapserver
hans@921: dpkg -i cgi-mapserver-gp_5.6.3-1~gp+1_i386.deb
hans@901: \end{lstlisting}
hans@901: 
hans@921: Provide a possibility to integrate MapServer properly and transfer
hans@921: configurations to MapServer during runtime:
hans@901: 
hans@921: \begin{lstlisting}
hans@921: cd /usr/lib/cgi-bin
hans@928: cp -i $ARTIFACT_SERVER_HOME/install/debian/umn-mapserver/gnv-wms .
hans@921: \end{lstlisting}
hans@921: 
hans@921: For setting proper contact details in the WMS Capabilities response,
hans@921: edit the file \verb+ $ARTIFACT_SERVER_HOME/conf/maptemplates/mapfile.vm+
hans@928: in the section WEB $\rightarrow$ METADATA.
hans@901: 
hans@901: \subsubsection*{Test of installation}
hans@921: Check for a sucessful installation via:
hans@901: 
hans@921: \begin{lstlisting}
hans@921: cd root
hans@924: curl \
hans@928: "http://localhost/cgi-bin/gnv-wms?service=WMS&request=GetCapabilities&version=1.1.1" \
hans@924: -o mapserver
hans@921: \end{lstlisting}
hans@901: 
hans@921: For a sucessful configuration, the response document \verb+ mapserver+
hans@921: contains a XML document describing the capabilities of the mapserver.
tim@1133: 
tim@1133: \subsection{Proxy-Script: Installation and Configuration}
ingo@1135: The Proxy-Script is required to allow the Map-Client to request external
ingo@1135: services. Security policies forbit and prevent requesting those services - like
ingo@1135: a GetFeatureInfo request - directly.
tim@1133: 
tim@1133: \subsubsection{Installation}
tim@1133: 
tim@1133: First make sure that python is installed on the operating system.
tim@1133: Otherwise install python using the following command:
tim@1133: 
tim@1133: \verb+ apt-get install python+
tim@1133: 
ingo@1135: Then the script itself must be published on the server by executing the
tim@1133: following steps:
tim@1133: 
tim@1133: \begin{lstlisting}
tim@1133: cd /usr/lib/cgi-bin
tim@1133: cp -i $ARTIFACT_SERVER_HOME/install/debian/ol-proxy/proxy.cgi .
tim@1133: \end{lstlisting}
tim@1133: 
tim@1133: \subsubsection{Configuration}
ingo@1135: The Proxy-Script can only communicate with servers it is allowed to.
tim@1133: To enable the communication to the server where the UMN-Mapserver is hosted
ingo@1135: or to other Server it is necessary to edit {\tt allowedHosts} in the
ingo@1135: Proxy-Script at line 18.
tim@1133: 
ingo@1135: There you have to replace the placeholder THISHOSTNAME with the name which
tim@1133: will be used to reach the GNV-Web-Client.
tim@1133: 
tim@1133: You can add further servers using the syntax which is given in the script.
tim@1133: 
tim@1133: \subsubsection{Test of installation}
tim@1133: 
tim@1133: It is possible to test the installation using the following command:
tim@1133: 
tim@1133: \begin{lstlisting}
tim@1133: curl http://localhost/cgi-bin/proxy.cgi?url=http%3A%2F%2Flocalhost
tim@1133: \end{lstlisting}
tim@1133: 
tim@1133: If localhost is allowed in the proxy-script the result might be this:
tim@1133: 
tim@1133: \begin{lstlisting}
tim@1133: <html><body><h1>It works!</h1></body></html>
tim@1133: \end{lstlisting}
tim@1133: 




