%vim:set tw=68:
% $Source: /home/bricks/source/greater/cvs/greaterrepository/GREAT-ERWeb/doc/great-er_web_administration.tex,v $
% $Id: great-er_web_administration.tex,v 1.8 2003-08-19 09:18:39 silke Exp $
\documentclass[a4paper,twoside,BCOR19mm]{scrbook}
\usepackage[latin1]{inputenc}
\usepackage{graphicx}
\usepackage{times}
\usepackage{fancyhdr}
\usepackage{lastpage}

%----------------------------------------------
% Document DATE and VERSION
% set these values when releasing a new version

\def\cleanunderscore#1_#2_#3{\expandafter #1\_#2\_#3}
\def\CVS$#1: #2 ${\expandafter\def\csname CVS#1\endcsname{\cleanunderscore#2}}
\CVS$Id: great-er_web_administration.tex,v 1.8 2003-08-19 09:18:39 silke Exp $

\newcommand{\documentdate}{23 July 2003}
\newcommand{\documentversion}{1.0.1}
\newcommand{\documentID}{\CVSId}

%----------------------------------------------

% Makros:
%       \Fig{figure}{text}      : creates an mbox around 'figure' and
%                                 writes 'text' at the bottom with leading
%                                 'Fig. section.figno:'.
%                                 Example:
%                                 \Fig{\epsfxsize30mm \epsffile{x.eps}}{the x}\\%       \FigNoEntry{}{}         : same as above, no entry in figures list
%
%       \FigNoCaption{}         : same as above, having no caption
%
%       \FigCaption{}           : line with figure caption, setting figure
%                                 counter and figures list

%****************************************************************************
%       Figure makro for graphics continously enumerated.
%

\newcounter{FigCnt}[chapter]
\newcommand{\Fig}[3]%
{
        \refstepcounter{FigCnt}
        \addcontentsline{lof}{figure}%
                {\protect\numberline{\thechapter.\arabic{FigCnt}}{#2}}
        \mbox{#1}
\nopagebreak

        {Fig. \thechapter.\arabic{FigCnt}: #3}
}

\newcommand{\FigNoEntry}[2]%
{
        \refstepcounter{FigCnt}
        \mbox{#1}
\nopagebreak

        {Fig. \thechapter.\arabic{FigCnt}: #2}
}

\newcommand{\FigCaption}[1]%
{
        \refstepcounter{FigCnt}
        \addcontentsline{lof}{figure}%
                {\protect\numberline{\thechapter.\arabic{FigCnt}}{#1}}

        %{Figure \thechapter.\arabic{FigCnt}: #1}
}

\newcommand{\FigNoCaption}[1]%
{
        \mbox{#1}
\nopagebreak

}

\begin{document}

%-----------------------------------
% define header/footer
% The settings here are for single page documents (only odd page set)

% for some pages latex switches back to pagestyle plain :-(
\fancypagestyle{plain}{%
	\fancyhf{} % clear all header and footer fields
	\fancyhead[LO,RE]{\footnotesize GREAT-ER Web Administration\\ \leftmark}
	\fancyfoot[RO,LE]{\footnotesize Intevation GmbH} % Author
	\fancyfoot[CO,CE]{\footnotesize \thepage/\pageref{LastPage}}
	% set the document title for the footer here!
	\fancyfoot[LO,RE]{\footnotesize \documentdate 
	\\\documentID}
	\renewcommand{\footrulewidth}{0.4pt}
}

% and now define pagestyle fancy
\fancyhead{} % clear all fields
\fancyhead[LO,RE]{\footnotesize GREAT-ER Web Administration\\ \leftmark}

\fancyfoot{}% clear all fields
\fancyfoot[RO,LE]{\footnotesize Intevation GmbH} % Author
\fancyfoot[CO,CE]{\footnotesize \thepage/\pageref{LastPage}}
% set the document title for the footer here!
\fancyfoot[LO,RE]{\footnotesize \documentdate 
\\\documentID}

\renewcommand{\footrulewidth}{0.4pt}

\pagestyle{fancy}

%-----------------------------------

\parindent0cm

%-----------------------------------
% TITLE PAGE
{
	\includegraphics[width=0.3\textwidth]{./brieflogo.eps}\\[0.1cm]

	 {\tt http://intevation.net}\\[2.0cm] 
}

% reenter the TITLE here
{
	\sffamily\bfseries\Large 
% e.g.:
	GREAT-ER II\\[0.5cm]
	\huge GREAT-ER Web Administration\\[4cm]

}

% a possible SUBTITLE
%\begin{flushleft}
%	\sffamily\bfseries\large 
%    	by Intevation GmbH\\[0.5cm]
%\end{flushleft}

\thispagestyle{empty}

\vfill

{\sffamily\small
	Intevation GmbH\\
	Georgstrasse 4\\
	49074 Osnabrück\\
	Germany\\
	\\
	Date: \documentdate
}


\newpage

%% PAGE 3
%\vspace{3cm}
%\centerline{\huge GREAT-ER Web Manual \small :: for version 2.0}
%\centerline{Geo-referenced Regional Exposure Assessment Tool for European Rivers}
%\vspace{1cm}
%\centerline{\Large Silke Reimer}
%
%\newpage

% PAGE 4

\vfill

This document has been designed with \LaTeX{}.
It is available as source code, PDF- and HTML-format.\\

%\begin{verbatim}
%$Revision: 1.8 $
%$Id: great-er_web_administration.tex,v 1.8 2003-08-19 09:18:39 silke Exp $
%
%\end{verbatim}

Version: \documentversion \\
Date: \documentdate \\
Author: Silke Reimer

\vfill

\begin{center}Copyright (c) 2003 Intevation GmbH.\end{center}

    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.2
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled ``GNU
    Free Documentation License''.

\tableofcontents

\chapter{Installation}

This chapter describes how to install GREAT-ERWeb on a Windows Server. You
can find these instructions also in the file INSTALL\_WIN.txt which is
located in the package.

\section{Requirements}

GREAT-ER Web requires a base installation of Python 2.1.3. If not installed on
your system already, follow the steps below:

\subsection{Install Python 2.1}
\label{sec:install-python}

\begin{itemize}
\item Download Python from http://python.org/. The most recent release of
   	   Python 2.1 at the time of writing is 2.1.3 which is available as

   	   http://python.org/ftp/python/2.1.3/Python-2.1.3.exe

           The page http://python.org/2.1.3/ has more information about release
           2.1.3 in particular (as opposed to Python in general). You might want
           to check the md5 sums listed there after the download.

\item Install Python-2.1.3.exe

\item Add the directory containing python.exe to the PATH.
\end{itemize}

Additionally an installation of the GREAT-ER database is required. If you
want to encrypt the database connection strings to this database, which is
highly recommanded, you need a webserver which is able to handle the https
protocol and proxy  requests.

\section{Installation on a Windows Server}

\subsection{Installing sources}
You should have gotten four Zip-Archives with the distribution of
GREAT-ERWeb:
\begin{itemize}
\item Zope-2.6.0-main.zip
\item Zope-2.6.0-products.zip
\item GREAT-ERWeb.zip		 
\item GREAT-ERWeb\_contrib.zip  
\end{itemize}

Now:
\begin{itemize}
\item change to a directory where you want to install GREAT-ERWeb.
  This directory is referenced as \verb+<HOME>+ below.

\item make directory GREAT-ERWeb
\item Unpack Zip-Archives into \verb+<HOME>\GREAT-ERWeb+
\end{itemize}


\subsection{Configuration}

\paragraph{Adapt sources to your paths}
\begin{itemize}
\item change to \verb+<HOME>\GREAT-ERWeb+
\item open 'config\_greater.bat'
\item edit GREATERWEB\_HOME and change it to \verb+<HOME>+

\item optionally you can edit the following ports:
    \begin{itemize}
    \item GREATERWEB\_PORT port the Zope server is listening to
	    The default port for the application is 8888.
	    You can change this to another port if needed.
	    Below we use port 8888 for the instructions.

    \item SCHEDULER\_CLIENT\_PORT\\
    SCHEDULER\_WORKER\_PORT\\
    SCHEDULER\_ADMIN\_PORT\\
        Relevant ports of the scheduler. \\
        Please {\bf note} that you have to edit a python script in the Zope
        Server if you edit the SCHEDULER\_CLIENT\_PORT (see section
        \ref{scheduler_conn}).

    \item WORKER\_ADMIN\_PORTS
        List of ports to administrate the greater workers. The number of
        ports corresponds to the number of workers that will be started.
        This number should be equal to your estimated average number of
        users that are starting a simulation at the same time to optimize
        the waiting time for the simulation results.
    \item GREATER\_TIMEOUT
        This is the number of minutes that a GREAT-ERWeb session will be
        held at minimum. Afterwards all temporary session data including
        the temporary session in the database will be deleted
    \item PYTHONEXE
        Specify here the directory containing python.exe (s. section
        \ref{sec:install-python}). This path will be included in PATH
        when deleting temporary files by scheduled tasks (s. section
        \ref{sec:delete-temp}).
    \end{itemize}
\end{itemize}


\paragraph{Change manager user}
\label{change_manager}

The default username for a manager is 'greater\_web'
with password 'greater4web'
This user should only be used for the initial session.
You should immediately create a local administrator and delete 
the greater\_web user:
\begin{itemize}
\item Start the Zope Server (see section \ref{start_zope})
\item In a Browser open [host]:8888/manage 
\item click on acl\_users in the left frame
\item click on 'add' and add a new user with password
\item grant roles 'manager' to this user
\item afterwards you should delete the user 'greater\_web'
\end{itemize}

\section{Importing and and reloading GREAT-ERWeb Application}

Importing and reloading a GREAT-ERWeb Application to the Zope Server
consists of mainly the same steps. The only difference is, that the old
GREAT-ERWeb Application has to be deleted before importing a new one.
Therefor if you are not updating but installing GREAT-ERWeb you can skip
the next section and go immediately to section \ref{import_app}. 

To fulfill all the following steps you have to make sure that the Zope
Server is running. Then in a browser
change to  \verb+ http://[host]:8888/greater/+.

\subsection{Deleting application}
\begin{itemize}
\item click in 'Root Folder' in the left frame
\item delete the folder 'greater'
\end{itemize}

\subsection{Importing application}
\label{import_app}
\begin{itemize}
\item click in 'Root Folder' in the left frame
\item click on 'Import/Export' in the main frame
\item insert 'greater.zexp' as Import file name
\item click 'Import'
\end{itemize}


\subsection{Configuration}

\paragraph{Adapting sources to your paths}
\begin{itemize}
\item click on 'greater' in the left frame
\item select the directory 'mapserv' in the main frame
\item add new objects of type LocalFileSystem with\\
    \begin{enumerate}
    \item
    {\bf id:} shapefiles \\
    {\bf basepath}:\\
    \verb+<HOME>\GREAT-ERWeb\GREAT-ERWebApp\mapserver+\\
    \item
    {\bf id:} mapserv\_generated\\
    {\bf basepath}:\\
    \verb+<HOME>\GREAT-ERWeb\GREAT-ERWebApp\var\mapserv\generated+\\
    \end{enumerate}
\end{itemize}

\paragraph{Adapting database and scheduler connection}
\label{scheduler_conn}
\begin{itemize}
\item In the menu in the left frame click on 'greater', then in the main
frame on 'zopeSession' and 'connection\_data'.
\item Choose tabulator 'Properties'.
\item Edit properties according to your needs. 

\end{itemize}

Please {\bf note}: Normally no editing should be necessary for {\em user}
and {\em password}. If you didn't change the parameter 
SCHEDULER\_CLIENT\_PORT in 'config\_greater.bat' no editing should be
necessary for {\em scheduler\_url} either.

\paragraph{Creating siteroot object}

\begin{itemize}
\item click on greater in the left frame
\item add new object of type siteroot with:
	\begin{itemize}
    \item title: not important
    \item base: $<$your server name$>$\\
        if you hide the Zope server behind a proxy (see below) this is the 
        server name of your proxy with the configurations of sections
		\ref{sec:ssl} and \ref{sec:proxy} this is
        this is \verb+ https://[host]:443+

    \item path: $<$your path after the server name$>$\\
        if you use the Zope server as it is, this has to be named /greater
        if you hide the Zope server behind a proxy (see below) you have to 
        insert the full path after the server name which is mapped to
        /greater 
	\end{itemize}
\end{itemize}

Please note that it is highly recommanded to use an SSL-enabled Webserver
as described in \ref{sec:ssl}
since otherwise all data including the database connection strings are
transferred unencrypted through the web!

\section{Starting and stopping GREAT-ERWeb}
\label{start_and_stop}

After starting the Zope server and model system GREAT-ERWeb is running and
available under
\begin{verbatim}
http://[host]:8888/greater/
\end{verbatim}

\subsection{Starting Zope Server}
\label{start_zope}
\begin{itemize}
\item change to \verb+<HOME>\GREAT-ERWeb+ in a DOS shell
\item start Zope server:
    start\_greater.bat
\end{itemize}

\subsection{Starting the model system}
\label{start_modell}
\begin{itemize}
\item Open a DOS shell and change to \verb+<HOME>\GREAT-ERWeb+
\item start model system:
    start\_modelsystem.bat
\end{itemize}

\subsection{Stopping model system and Zope server}
\label{stop_modell}
\begin{itemize}
\item Open a DOS shell and change to \verb+<HOME>\GREAT-ERWeb+
\item stop model system by starting
    stop\_modelsystem.bat
\item in a Browser open [host]:8888/manage 
\item Click on 'Control\_Panel' in the left frame
\item Click on 'shutdown' in the main frame to stop the Zope
server
\end{itemize}

\chapter{General configuration}

\section{Deleting temporary files}
\label{sec:delete-temp}

The GREAT-ERWeb Application is producing temporary files on the file system
which should be removed from time to time. Therefor the following
mechanisms are provided:

\begin{itemize}
\item The script delete\_temp\_files.bat, located at
  \verb+<HOME>\GREAT-ERWeb+ removes temporary map-images and result-dBase
  files that are older than 30 min.

  Please run this script from time to time to delete files that are not
  needed any more. Therefor go to 
  'Start/Settings/Controlpanel/Scheduled Tasks/Add scheduled tasks' and add
  this batch file.

  {\bf Note:} If you want to change the time, that map images or result dBase files are
  guarded, please open remove\_temp\_files.py and edit the entries at the
  beginning of the script. 

\item Each time the Zope Server is restarted all temporary files including the
  catchment data are deleted.

\item If you want to delete all temporary files without restarting the Zope
Server you can run the script
\verb+<HOME>\GREAT-ERWeb\delete_all_temp_files.bat+.
\end{itemize}

\section{Adapt model system to the estimated number of simulations}

You should start as many greater workers as simulation will be run at the
same time. To do this please follow the following steps:
\begin{itemize}
\item stop model system (see section \ref{stop_modell}
\item edit WORKER\_ADMIN\_PORTS in config\_greater.bat. You should indicate as
  many ports as you want workers to be started. 
\item start model system (see section \ref{start_modell}
\end{itemize}

\section{Rewrite ZopeConnection to SSL}
\label{sec:ssl}

The following directives should be placed in the httpd.conf of Apache if
you want to redirect all Zope Connection to SSL. This is highly recommended
since this ensures an encrypted transmission of all data. The directive
assume that the SSL-enabled Webserver is listening on port 443.

\begin{verbatim}
RewriteEngine On
RewriteCond %{SERVER_PORT}  !^443$
RewriteRule ^/greater/(.*)  https://%{SERVER_NAME}/greater/$1 [L,R]
\end{verbatim}

\section{Configuration to hide a Zope Server behind an Apache Server}
\label{sec:proxy}

To hide a Zope Server behind an Apache Server place the following
directives in the httpd.conf of the (SSL-enabled) Apache:

\begin{verbatim}
<IfModule mod_proxy.c>
    #
    # Proxy Server directives. Uncomment the following lines to
    # enable the proxy server:
    #
  #<IfModule mod_proxy.c>
  ProxyRequests On

  <Directory proxy:*>
      Order deny,allow
      Deny from all
      Allow from all
  </Directory>
ProxyPass               /manage http://localhost:8888
ProxyPassReverse        /manage http://localhost:8888
ProxyPass               /greater http://localhost:8888/greater
ProxyPassReverse        /greater http://localhost:8888/greater
ProxyPass               /misc_ http://localhost:8888/misc_
ProxyPass               /p_ http://localhost:8888/p_

</IfModule>
\end{verbatim}

Additionally you have to load the module mod\_proxy.c

\section{Integrate a new catchment}

The integration of a new catchment in GREAT-ERWeb requires that the
catchment is correctly build and uploaded into the database. Furthermore
you need 
\begin{itemize}
\item the file named 'greater.map' which is the template configuration
file for the UMN MapServer, 
\item the program named 'shp2img.exe', 
\item CATCHBOUND and RIVERNET shapefiles of the catchment and information
about its spatial extent. 
\end{itemize}

greater.map and shp2img.exe are included in the Zip-Archive mapfiles.zip.

If you have all this information you can create and upload the
MapServer configuration file and the reference image.

\subsection{Creating and uploading mapfile}
\begin{itemize}
\item Open greater.map and edit it at the indicated places. These are namely:
    \begin{description}
    \item [NAME] insert the catch\_id of the catchment
    \item [EXTENT] insert the spatial extent of the catchment
    \item [in REFERENCE: EXTENT] insert spatial extent of the catchment
    \end{description}

\item Then save greater.map as MAPFILE.map

\item Load MAPFILE.map into the database into the table bin\_obj\_tab
with\\ 
    \begin{tabular}{|l|l|}\hline
    object\_id& catch\_id\\
    obj\_type& CATCHMENT \\
    obj\_sub\_type& MAPFILE\\
    file\_type& map\\\hline
    \end{tabular}
\end{itemize}

\subsection{Create and uploading reference.png}
\begin{itemize}
\item open MAPFILE.map
\item change SIZE to 200 175
\item uncomment line after SIZE 'IMAGETYPE PNG'
\item open a DOS shell
\item change to the directory where MAPFILE.map is located
\item copy catchbound and rivernet shapefiles to the current directory
\item copy shp2img.exe to the current directory
\item run shp2img with the following flags:\\
        \verb+shp2img.exe -m MAPFILE.map -o REFERENCE.png+

\item Load REFERENCE.png into database, table bin\_obj\_tab
with\\
    \begin{tabular}{|l|l|}\hline
    object\_id& catch\_id\\
    obj\_type& CATCHMENT \\
    obj\_sub\_type& REFERENCE\\
    file\_type& png\\\hline
    \end{tabular}
\end{itemize}
%-------------------------Appendix-------------------------------------

\begin{appendix}

\include{gnufdl}

\end{appendix}


\end{document}



