%\documentclass{book}
\documentclass[12pt,a4paper, twoside]{scrreprt} % KOMA-class Neukam and Kohm, scrbook alternatively
%\documentstyle[makeidx]{book}
\makeindex
\include{rsat_latex_commands}

\begin{document}


\RSATtitlePage{Web server configuration for \RSAT}

% \title{Regulatory Sequence Analysis Tools \\
% Web server installation}
% \author{
% 	Jacques van Helden \\
% 	\email{jvhelden@ulb.ac.be} \\
% 	\bigre 
% }
% \maketitle

\newpage
\tableofcontents
\newpage

\chapter{Web server configuration for \RSAT}

\section{Description}

This documents describes the installation procedure for the web server
of the \textbf{Regulatory Sequence Analysis Tools} (\RSAT).

It assumes that you already installed the perl scripts and the
genomes, as described in the \RSAT installation guide.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Web server installation

\section{Installing a local web server}

The Regulatory Sequence Analysis Tools include a web server, which
offers a user-friendly interface for biologists. The main server is
available for academic users at \\
\url{http://www.rsat.eu/}

Some additional mirrors have been installed in different countries.

\subsection{Web server pages}

The web pages are located in the directory \file{rsat/public\_html},
which contains both the HTML pages, and the CGI scripts.

\subsection{Apache modules}

The \RSAT interface relies on CGI (for the earlier tools) and PHP (for
the most recent tools). These modules should be installed on the web
server, and activated in the Apache configuration files. Note for MACOSX MAMP users : these modules are already activated, as well as cgi-script.

Log in as super-user of your server, open the main apache
configuration (\file{/etc/apache2/httpd.conf}) witha text editor, and
check that the following lines are uncommented (suppress the leading
\# if any).

\begin{lstlisting}
LoadModule cgi_module libexec/apache2/mod_cgi.so
LoadModule php7_module libexec/apache2/libphp7.so
\end{lstlisting}
                                                        
For Apache version 2.2, you also need to activate the perl module
\option{mod\_perl.so}, whereas in version 2.4 this module does not
appear anymore (Perl seems to be included in the server).

Uncomment the following line:

\begin{lstlisting}
AddHandler cgi-script .cgi
\end{lstlisting}

Optional : it is convenient to associate a plain/text mime type to
extensions for some classical bioinformatics files, in order to
display them directly in the browser rather than proposing users to
download them.

In the config file \file{httpd.conf}, locate the place with the AddType
directives, and add the following lines.

\begin{lstlisting}
AddType text/plain .fasta
AddType text/plain .bed
\end{lstlisting}

For the Network Analysis Tools, you also need to adapt the PHP
parameters in order to support larger data sizes for Web forms (post)
and file uploads.


After having found the php.ini file for your operating
system \footnote{
  \begin{itemize}
  \item Ubuntu:  \file{/etc/php5/apache2/php.ini}.
  \item Mac OSX Yosemite: copy the file \file{/etc/php.ini.default} to
    \file{/etc/php.ini} and edit this copy.
  \end{itemize}
}, modify the following parameters:

\begin{lstlisting}
upload_max_size=100M
post_max_size = 100M
\end{lstlisting}

%% \subsubsection{PHP module for Mac OSX}

%% If your server is running under Mac OSX, you need to install a recent
%% version (at least v5) of the php module, which can be found at the
%% following site.

%% \url{http://www.entropy.ch/software/macosx/php/}


\input{ig_apache_config.tex}


\subsection{Testing the web server}

To test the web server, open a web browser and connect your \RSAT
server (of course you need to adapt the following URL according to the
actual IP address of the server).

\url{http://www.myserver.mydomain/rsat/} 

If the connection works, try to execute the demonstration of the
following pages.

\begin{description}
\item[\program{supported organisms}] to check that genomes have
  been insalled.
  
\item[\program{retrieve-seq}] to test the correct installation of
  genomes.

\item[\program{oligo-analysis}] to test the correct installation of
  background oligonucleotide frequencies.

\item[\program{feature-map}] to test the correct installation of the
  graphical librairies.
\end{description}

\section{Managing a local web server}

\subsection{Access logs}

Each time a script is executed via the \RSAT server, some basic
information is stored in a log file. This information is minimal: it
is restricted to the time, name of the script executed, and the IP
address of the client machine. We do not want to store any additional
information (e.g. selected organism, lists of genes), for obvious
confidentiality reasons.

The log files are saved in the directory \file{\$RSAT/logs}. There
is one file per month.


\subsection{Cleaning the temporary directory}

The web server stores result files in a temporary directory
\file{\$RSAT/public\_html/tmp/}. These files should remain 3 days on
the server, in order to allow users to consult their results.

\subsubsection{Manual cleaning}

The \RSAT package includes a make script to clean old files in the
temporary directory.

\begin{lstlisting}
cd $RSAT
make -f makefiles/server.mk clean_tmp
\end{lstlisting}

This command cleans all the files older than 3 days. You can clean
more recent files by modifying the variable CLEAN\_DATE.

\begin{lstlisting}
make -f makefiles/server.mk clean_tmp  CLEAN_DATE=1
\end{lstlisting}

This will clean all files older than 1 day.

\subsubsection{Automatic cleaning}

The automatic management of the temporary directory can be greatly
facilitated the \program{crontab} command. For this, you need to add a
command to your personal \texttt{crontab} configuration file.

\begin{enumerate}
\item Start to edit the crontab command file

\begin{lstlisting}
crontab -e
\end{lstlisting}

This will open your \file{crontab} file with your default text editor
(this default editor can be specified with the environment variable
EDITOR or VISUAL).

\item Add the following line to the \file{crontab} file. 

\begin{lstlisting}
02 04 * * * make -f [RSAT_PARENT_PATH]/rsat/makefiles/server.mk clean_tmp
\end{lstlisting}

This will execute the make script \file{server.mk}, with the target
\texttt{clean\_tmp}, every day, at 04:02 AM. 

\item Save the modified crontab file and close your text editor.

\end{enumerate}

In principle, you will receive an email from \program{crontab} each
time the command is executed.

Note that the command \program{crontab} takes effect only if the
system administrator has activated the command \command{cron}. If you
notice that the temporary files are not properly cleaned, please
contact your system administrator to check the cron command.

\end{document}



\section{Compiling the Perl stub for Web services}

Web services \footnote{beware, this is not the same as Web server}
enable external programs to remotely address queries to your Web
server. The \RSAT Web server relies on Web services for various
purposes (e.g. synchronizing genomes between servers). Besides the
Network Analysis Tools are based on a multi-tier architecture relying
on Web services.

To use the \RSAT and NeAT Web services, you need to compile the Stub
in order to synchronize the Perl modules of your client with the
service specification of the server.

\begin{lstlisting}
## Compile the stub.
## Your computer will open a connection to the Web services server 
## and collect the WSDL specifications of the supported services.
cd $RSAT
make -f makefiles/init_RSAT.mk ws_stub

## Test the connection to the Web services
cd $RSAT/ws_clients/perl_clients
make test
\end{lstlisting}
%$

