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:
tim@1136: \subsection{Preparations}
tim@1136:
tim@1136: In some steps it is required to use templates wich are packed in
tim@1136: \verb+ artifact-server-$VERSION.tar.bz2+ to get access to those files.
tim@1136:
tim@1136: Please extract the tar.bz2 file as explained in
tim@1136: Chapter~\ref{ref:artifact-server-install},
tim@1136: p.~\pageref{ref:artifact-server-install}.
tim@1136:
tim@1136: The complete document use the system-variable \verb+$ARTIFACT_SERVER_HOME+
tim@1136: to refer the root-directory of the Artifac-Server.
tim@1136: It might be helpful to export this variable using the following command:
tim@1136:
tim@1136: \verb+ export ARTIFACT_SERVER_HOME=/opt/artifact-server+
tim@1136:
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:
tim@1136: \begin{lstlisting}
tim@1136: apt-get update
tim@1136: apt-get install sun-java6-jdk
tim@1136: \end{lstlisting}
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}
tim@1136: java version "1.6.0_20-b02"
tim@1136: Java(TM) SE Runtime Environment (build 1.6.0_20-b02)
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}
tim@1136: - #JAVA_HOME="/usr/lib/jvm/java-6-sun/"
tim@1136: + JAVA_HOME="/usr/lib/jvm/java-6-sun/"
tim@1136:
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:
hans@901: -
hans@901:
hans@901: +
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
tim@1136: \verb+ /etc/init.d/apache2 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}
tim@1136: cp -i $ARTIFACT_SERVER_HOME/install/debian/apache2/gnv 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:
tim@1136: If there are libraries which are required by the Mapserver but not
tim@1136: installed yet run the following command:
tim@1136: \begin{lstlisting}
tim@1136: apt-get -f install
tim@1136: \end{lstlisting}
tim@1136:
tim@1136:
tim@1136: 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 .
tim@1136: chmod +x 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:
tim@1136: The Mapserver will need fonts for rendering lables in the map.
tim@1136: To provide this it is required to install the freefonts.
tim@1136: \begin{lstlisting}
tim@1136: apt-get install ttf-freefont
tim@1136: \end{lstlisting}
tim@1136:
tim@1136:
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 \
tim@1136: "http://localhost/cgi-bin/gnv-wms" \
hans@924: -o mapserver
hans@921: \end{lstlisting}
hans@901:
hans@921: For a sucessful configuration, the response document \verb+ mapserver+
tim@1136: contains a Value which contains the following message of the mapserver.
tim@1136:
tim@1136: TODO: QUERYSTRING WAS EMPTY HINZUFUEGEN
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@1136: curl http://localhost/cgi-bin/proxy.cgi?url=http%3A%2F%2Flocalhost/cgi-bin/mapserv-gp
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@1136: TODO: QUERYSTRING WAS EMPTY HINZUFUEGEN
tim@1133: \end{lstlisting}
tim@1133: