INSTALLATION INSTRUCTIONS FOR MOBYLE
************************************


1 - Requirements:
=================

- Any machine running a unix-like Operating System.
- A CGI-enabled web server (such as Apache with a loaded mod_cgi and optionally the rewrite engine).
- Python, >=2.5 & <3.0
- The following Python libraries:
 	+ simpletal, >= 4.1 & <5.0
 	+ simplejson, >= 1.7.1
 	+ python imaging library (with libpng, zlib and freetype support), >= 1.1.5  
	+ lxml >=2.2.4 ,

(remark: pyCaptcha is not required anymore as it was integrated in Mobyle )

- Optional:
        + a biological sequence/alignment format converter software. We recommend squizz
          (ftp://ftp.pasteur.fr/pub/gensoft/projects/squizz-0.99b) and we provide a plugin for it.
        + a batch system, such as SGE (http://gridengine.sunsource.net/), PBS/Torque 
          (http://www.clusterresources.com/pages/products/Torque-resource-manager.php), or LSF.
        + python-drmaa http://drmaa-python.googlecode.com/ if you use SGE via DRMAA, PBS/Torque
          via DRMAA, or LSF via DRMAA. We do not provide a non-DRMAA access to Torque or LSF.
        + FedStage DRMAA for LSF (http://sourceforge.net/projects/lsf-drmaa/) if you use LSF
        + if you use Torque/PBS via DRMA enable this option at compilation time. 
        + dnspython >=1.5.0 is helpful to check user emails domain validity.
        + golden (ftp://ftp.pasteur.fr/pub/gensoft/projects/golden/) is helpful to directly load 
          biological sequences from databanks into the web portal.
        + python-openid >=2.2.4 (http://openidenabled.com/files/python-openid/packages/python-openid-2.2.4.tar.gz)
          to enable OpenId authentication.
        + the service descriptions (ftp://ftp.pasteur.fr/pub/gensoft/projects/Mobyle/)
          are collections of "ready-to-use" service descriptions (programs, workflows, or viewers)
          maintained by the Institut Pasteur.
        + the jing java library and dependencies (http://code.google.com/p/jing-trang/downloads/list)
          in case you want to modify service descriptions or create your own. It is not required
          to operate Mobyle, but provides detailed error messages that can help you create valid
          service descriptions.
          
2 - Technical overview:
=======================

A "Mobyle" server does not run any specific daemon (apart from
the web server). When a user launches a job, it is actually running a cgi that
runs a bioinformatics program in a subprocess. If the subprocess runs
for more than a certain time, it detaches itself, and continues
monitoring the execution until its end. The "web server user" is therefore
the one that runs every request and user permissions should be done so
that it can access and run every data, program, and parameter of the
Mobyle configuration.

3 - The Mobyle archive tree:
============================

Doc => Documentation

Example => A few sample files.

Local => Configuration, local parameters and code for the Mobyle
         system.

Schema => The schema files that define the XML data model and the validation
         rules for service descriptions.

Src => Mobyle source code:
	* the Mobyle folder contains the "core" code for the Mobyle
          Server.
	* the Portal folder contains the code for the web portal that
          provides an access to the system.

Tools => A few utilities and scripts.

niad => (only if you choose a Mobyle+BCBB tarball) root of 2 mobyle companion: 
  * BCBB Mobyle Interface Designer (BMID)
  * BCBB Mobyle Pipeline System (BMPS)

4 - Installation steps:
=======================

4.1 - Make sure every required dependence/software is present.
--------------------------------------------------------------

4.2 - Perform the installation.
-------------------------------

To install Mobyle, you need to provide 3 different paths, where all
files will be installed, and 2 flags to install BMID and BMPS (these 2 flags are only
available if you download a Mobyle+BCBB tarball) :

    python setup.py install \
      --install-core=/path/where/to/install/core/files \
      --install-cgis=/path/where/to/install/cgis/files \
      --install-htdocs=/path/where/to/install/html/files
      --install-bmps    
      --install-bmid
      
  - The `--install-core' option specifies the directory where to install the Mobyle
    core files (code, tools, example, documentation, ...).

  - The `--install-cgis' option specifies the directory where to install the Mobyle
    portal cgis to be executed by the web server.

  - The `--install-htdocs' option, will be used as the Mobyle document
    root, which will contain the portal static documents (in a 'portal' subfolder),
    the users sessions, the jobs and the programs definitions (in a 'data'
    subfolder). Make sure this subtree is readable by the web server
    user. Furthermore, the permissions on subfolders 'sessions' and
    'jobs' have to be writable by Apache.
    
   - The --install-bmps flag, indicate that the installer will install BMPS, 
     the BCBB Mobyle Pipeline System. BMPS will be installed in Mobyle cgis location.
     (this option is available for Mobyle+BCBB tarball only).
     
   - The --install-bmid flag, indicate that the installer will install BMID, 
     the BCBB Mobyle Interface Designer. BMID will be installed in Mobyle cgis location.      
     (this option is available for Mobyle+BCBB tarball only).
     
4.3 - Configure Mobyle and Apache.
----------------------------------

Go to your freshly installed "Mobyle core" directory (from now on, you can remove
 the sources), and create the configuration file using the provided template:

cp Example/Local/Config/Config.template.py  Local/Config/Config.py

In order to have a working installation, you need to edit the various configuration directives.
The documentation describing the configuration of Mobyle and Apache is the configuration manual 
Doc/Admin/how_to_configure_mobyle.pdf.

4.4 - Services descriptions deployment.
---------------------------------------

The deployment of services using Mobyle does not install the programs, it just makes them 
accessible on the web. You must install separately the bioinformatics software corresponding 
to the descriptions.

We provide a set of "ready-to-use" services descriptions (programs, workflows, viewers), which 
are available in the following ftp website: ftp://ftp.pasteur.fr/pub/gensoft/projects/Mobyle/. 
For Mobyle 1.0, use Programs-1.3.tgz or higher. Workflows and Viewers are new to version 1.0.

For instance, to deploy pasteur-provided program descriptions:
  - download the "Programs-xx.tgz" file,
  - expand the archive in the Programs subfolder,
  - configure Mobyle according to the bioinformatics software installed on
    your platform (see LOCAL_DEPLOY_* directives in the configuration manual),
  - use the mobdeploy script which is located in the Tools subfolder (for more details see associated
    README).
     
Make sure, once the programs descriptions are deployed, that they are readable by the web server. 
For more explanations about services deployment see the associated Tools/README file and the 
configuration manual. 

5 - Tests and troubleshoot:
===========================

Try to connect to your portal. The url of the portal is:
    ROOT_URL/CGI_PREFIX/portal.py

You should see the welcome page at the center and, on left, the
available programs presented in a hierarchical tree.

If you have any trouble, it will be very useful to check :
 - the apache error log, if you have a "500 Internal Server Error"
 - the Mobyle error_log (located in previously the LOGDIR configuration directive), 
   if something seems goes wrong but there is no error 500. 

Here are a few frequent problems that can occur:
 
* Instead of the welcome page I see 'Internal Server Error'.
    -> Make sure the web server has the writable permissions on the
       --install-htdocs /sessions subfolder.

* I do not see the installed services appear in the left menus and/or their forms.
    -> Make sure the files in data/programs/ are readable the web server user.

* After filling the CAPTCHA, the Portal freezes: 
    -> Check the Mobyle error log for an "IOError: decoder jpeg not available" message.
    If so, the PIL package was not compiled with jpeg support. You must have libjeg installed
    before to install PIL. Check if the PIL install script detects your libjpeg, PIL shows a
    summary after building (python setup.py build_ext -i).

* After launching a job, I have : Mobyle Internal server error.
    -> Check the Mobyle error log for an "AsynchronRunner : CRITICAL ... __init__: exec child
    caught an error" message. If you find it, make sure the python module Src/Mobyle/RunnerChild.py
    is executable by the web server user.
 
If your problem is not among those covered above then please contact
us at mobyle-support@pasteur.fr.

6 - Mailing list:
=================

There is a mailing list dedicated to Mobyle server administrators, called 
"mobyle-users". This list discusses new releases, related software announcements,
administration and development issues, etc. This is a moderated and low traffic list.

You can subscribe to Mobyle users at:
    http://sympa.pasteur.fr/wws/subrequest/mobyle-users
