=========================================
programInstaller HOWTO
=========================================

Mobyle currently allows administrators to publish programs that are either *local* or *imported*. The `programInstaller` script is used to *publish* them on the server, making them available to the public. This script also handles *program indexing*.

Overview
========
Once a Mobyle server has been installed in a **MOBYLEHOME** directory on the system, the program definitions (i.e., the xml files that describe them to the Mobyle system) are stored in two directories:

#. the **MOBYLEHOME**/Programs directory contains program definitions that the administrator has downloaded from distributions,
#. the **MOBYLEHOME**/Local/Programs directory contains custom program definitions that have either been created de novo by the server owner, or that he modified to fit his own needs.

In order to publish the programs, the program definitions are copied to a web-accessible directory defined by the server configuration in the **DOCUMENT_ROOT/PROGRAMS_URL** directory. Therefore, these files will be directly accessible from the Web on the **ROOT_URL/PROGRAMS_URL** url. This document refers to this directory as **www-programs**.

The imported program definitions are downloaded *via* the Web from the **www-programs** directory of the remote servers. These program definitions are stored in the PROGRAMS_CACHE_PATH directory, which we refer to as **www-cache**.

The programs index is stored in the **MOBYLEHOME/registry_index.json**.

Configuration
=============
The configuration of published/imported programs is located in the Local/Config.py file.

The publication of local services is configured by the **LOCAL_INSTALL_ORDER**, **LOCAL_INSTALL_INCLUDE**, and **LOCAL_INSTALL_EXCLUDE** directives. Programs are identified by a list of names that can include jokers.

e.g.::

  LOCAL_INSTALL_ORDER=['include' , 'exclude' ]
  
  LOCAL_INSTALL_INCLUDE = [ 'golden', 'clustalw*', 'dnadist', 'fitch', 'kitsch', 'neighbor', 'protdist', 'clique', 'dnapars', 'mix', 'pars', 'protpars', 'consense', 'drawgram', 'drawtree', 'unroot', 'blast2', 'muscle' ]
  
  LOCAL_INSTALL_EXCLUDE=[]

The exportation of services to other portals is defined by the **EXPORTED_SERVICES** directive, which lists these services.

e.g.::

  EXPORTED_SERVICES = [ 'golden', 'abiview' ]

The importation of services from other portals is defined by the **PORTALS** directive, a dictionary that defines external portals the following way:
- the key is the nickname of the portal, as it will appear in the programs list of the portal
- for each portal:

  + url is the path to the directory that contains all the cgis (such as job_submit.py).
  + help is the e-mail of the remote portal maintainer, that receives help requests about his job.
  + repository is the path to the directory that contains all the published programs.
  + programs is the list of imported programs.

e.g.::

  PORTALS={'portal1': {
            'url': 'http://otherdomain.fr:port/cgi-bin/MobylePortal',
            'help' : 'help@otherdomain.fr',
            'repository': 'http://otherdomain.fr:port/MobyleData/programs',
            'programs': ['clustalw-multialign']
            }
        }

Usage and options
=================

The ``programInstaller`` script is located in the **$MOBYLEHOME/Tools** directory. Before to run it, you should make sure that:

 - your current user has the permissions to read and write the files that belong to the Mobyle user (e.g., apache user).
 - your **MOBYLEHOME** environment variable is correctly set.

Below are a few examples of how you can use the programInstaller utility. More extensive help can be obtained by typing::

$./programInstaller.py -h

+ install everything according to the configuration::

  $./programInstaller.py install

+ install/update the *blast2* local program according to its configuration::

  $./programInstaller.py -p blast2 install

+ remove the *blast2* local program according to its configuration::

  $./programInstaller.py -s local -p blast2 clean

+ install the remote program *seqret* located on the *mylab* server according to its configuration::

  $./programInstaller.py -s mylab -p seqret install

+ only update the program index (in case the index file has been lost for instance)::

  $./programInstaller.py index
