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: