Installing the www interface for a simple utilisation of ESPript

This page is for the site administrators who want to install ESPript version 2.3, ESPript.cgi version 3.x and eventually ENDscript on their site.

Upgrading from a previous release

If a previous version of ESPript is already running on your site, please install this new version in another directory. You should be able to reuse the configuration file, only if you come from a 2.0; www 2.5 release. cf. under for details.

Requirements

Before installing ESPript.cgi, you need a unix machine, with the following installed on it:

• ESPript version 2.3.
• A www server (I used the apache free server) with php enabled.
• perl 5.004 or higher
• CGI.pm version 2.752 or higher (the higest, the best)
• libwww-perl version 5.23 or higher. optional.
• ghostscript version 5.10 Aladdin optional.
• convert (from the ImageMagick package) version 5.3.3 or higher optional.
• gzip version 1.2.4 (warning !!! the 1.2.3 is buggy and should not be used !!!)
• D.S.S.P. by Wolfgang Kabsch and Chris Sander. Warning, you need the CMBI version by Elmar.Krieger@cmbi.kun.nl / November 18, 2002 or a more recent release, as only from this release there is some ESPript-contributed code.
• M.S.M.S. (from Michel Sanner)
• Local databases may be necessary if you want to install ENDscript.

If you want also to install and use ENDscript, you should install the following programs, too:

• BLAST
• C.N.S.
• BOBSCRIPT
• MOLSCRIPT
• DINO
• CLUSTALW
• MULTALIN
• PROFIT

If you do not want to install ENDscript, you must proceed as follows:

• open with an editor the file: html/common/banner.inc
• Search the line: $NO_ENDSCRIPT = 0;
• Replace this line with $NO_ENDSCRIPT = 1;

Retrieving and installing the www interface

After having retrieved the tar file through ftp, please run tar xvzf on it to get the whole hierarchy. Now, you'll have a few things to do in order to configure and run the whole stuff:

• Copy some files to the src and bin directories
• Run the install.pl script for the first time.
• Edit the configuration file if necessary, and run install.pl --conf
• Run install.pl --make to compile some fortran programs.
• Choose a security mode, and run install.pl --secu
• Modify the server configuration
• Run the cleaning procedure through the cron utility.
• enable the software.

If you need ENDscript, you must copy the following files to the bin directory, not retrieved with the www interface mainly for licensing reasons:

• dsspcmbi
• bobscript
• molscript
• profit

Moreover, you must also install the above mentionned programs (it could be done in the  bin directory as well) :

• convert (from the ImageMagick package)
• M.S.M.S.
• BLAST
• C.N.S.
• DINO
• CLUSTALW
• MULTALIN

Of course, you may not copy any other binary inside the bin directory, as the directory will be used only by ESPript

Now, run the perl script install.pl as follows:

./install.pl --hlpburl /ESPript --cgiurl /ESPript/cgi-bin

What does install.pl do ?

install.pl goes to the cgi-bin directory, reads the file called ESPript.cgi.conf-distrib, and writes a new file called ESPript.cgi.conf, with correctly setting the perl variables $ROOTDIR and $CGIURL. Nothing more than that yet.

You have to manually edit the cgi script ESPript.cgi.conf-distrib in order to take into account of the specificities of your site. The parameters to configure are perl variables, whose values are set inside the sub init_all. However, every parameter has a generally acceptable default value, so that you have to take care of this only if the default value is not OK for you. The only required parameters have already been set by install.pl.

Upgrading from an older release

If you already installed a 2.0 version of ESPript (www 2.5), you should already have a correct configuration file. You may thus edit the new file, using the parameters of the old file (copy-and-paste in your editor).

The printer configuration

You can skip this section if you do not want to let your users directly print the calculated postscript file to one of your printers.

Output file types

You can skip this section if you the default file types (Postscript, png 100dpi, png 300dpi, etc.) are OK for you. If you do not want to produce any file type other than postscript, you don't need ghostscript nor ImageMagick.
We suggest using essentially png files, excluding gif or tiff files: ImageMagick now does not use compression for those file types (because of some licensing problems...), so that those files may be very huge (especially in 300dpi).

SRS or 3DBBROWSE SERVERS, or local pdb files

ESPript_exe.cgi is now able to query SRS or 3DBROWSE servers, to get dssp or pdb files, or to get dssp/pdb files from a local file system. It is possible to configure the script to make him query the most efficient server (generally the local file system if the pdb is locally available, or the server nearest from you).
NOTE - For local filesystems only: the pdb files must be all stored in the same directory.

Disabling SRS or 3DBbrowse queries

Limits

The default values for those parameters should be correct, so you can skip this section. However, if you want to modify some limitations, may be you should have a look here.

Other parameters

The default values for those parameters should be correct, so you can skip this section.

Other environment variables

You may configure any environment variable in the configuration file; some of them are necessary for helper applications, especially if you choose to install ENDscript. Please have a look to the automatically generated configuration file, and to the following scripts (found under html/scripts directory):

• blast.csh ($BLASTDIR, $BLASTDB)
• bob.csh ($BOBDIR)
• cns.csh ($CNSDIR)
• superpo.csh ($BINDIR, already configured however).

Other configurable directories

Those parameters are given a "reasonnable" value, however you can modify this value if necessary.

You must run the perl script install.pl as follows, after each modification of the configuration file:

./install.pl --conf

What does install.pl --conf do ?

• goes to the cgi-bin directory, reads the file called ESPript.cgi.conf, and replaces the subroutine called init_all found in the main cgi script, by the subroutine found in the conf file.
• Rewrites a few html files (see the extensions .html-distrib) to update the links.

You may now run

install.pl

./install.pl --make

This just calls the make utility, to compile the fortran programs.

Two securities modes may be used: the first one is called "low security", as the second one is called "high security".
The problem is that several files and directories must be written by your web server. Thus the permissions of those files must be correct. There are two ways to achieve those requirements:

• Give full access to those files to everybody (low security).
• Give the ownership of those files to the web server (high security).

Low security

This mode is called "low security" simply because it is considered as a security hole to have files and directories with the permissions bits 777. However, you may consider that this risk is somewhat limited, because of the few number of files involved. You may install ESPript in low security mode without working as root.
To configure this mode, just type:

./install.pl --secu=low

High security

In this mode, you must be able to give to the web server user (generally nobody or any other restricted account) the ownership of some files. Thus, you must be root to configure this security mode.:

su (working as root)
./install.pl --secu=high --user=nobody

You must configure the mime types of postscript and pdb files on your server: the right column in the following table gives the line which be present in the srm.conf, unless you prefer to declare the type in the mime.types file (Only if your server is Apache, see your server's documentation if not). Do not forget to restart the server after any configuration change, however

The httpd.conf file should also be correctly configured, with scriptalia and alias directives, so that the home page and the cgi script can be correctly retrieved by the http server (see above the switches --hlpburl and --cgiurl). Here is an example, you could copy and paste at least if Apache is your web server:

    ScriptAlias /ESPript/cgi-bin "/usr/local/ESPript/cgi-bin"
    Alias /ESPript "/usr/local/ESPript/html"
    <Directory "/usr/local/ESPript/current/html">
        Options FollowSymLinks
        AllowOverride None
        Order allow,deny
        Allow from all
    </Directory>
    <Directory "/usr/local/ESPript/current/cgi-bin">
        Options FollowSymLinks ExecCGI 
        AllowOverride None
        Order allow,deny
        Allow from all
    </Directory>

WARNING - Please note you should not export through your web server the whole ESPript hierarchy: some programs are found here, which are not free software. Thus you could get legal problems. Only two directories need to be seen by the web server: the html directory (home page), and the cgi-bin directory. That's all.

When the users upload files, those files are stored in the directory pointed to by the $TMPDIR variable. If they press the button "Exit", those files are destroyed. However, many users will forget to do so, or some communication problem will make this impossible. It is thus indispensable for the web master to clean that directory on a regularly basis. ESPript_exe.cgi helps you with providing two tools:

The .lck files

Every time someone calls the cgi script, a "session id" is allocated by the system: let's suppose 1000 is the allocated session id. The script will create a directory, named 1000. All session-related files are kept inside this directory, namely a file called lck. The session id is kept by the client (through a hidden field in the form), so that every time a button is pressed, ESPript_exe.cgi is able to retrieve the previously uploaded files. Besides, a line is added to the .lck file, so that it is possible for the administrator to know more or less how the script is used... Please note that this file is not destroyed when the Exit button is pressed.

The ESPript_clean.pl script

When you call this script as follows:

ESPript_clean.pl 45

ESPript is now installed, but it is disabled: you must enable ESPript before the users can play with it. This is done with the command:

./install.pl --enable

If later you want to disable ESPript, for example to install a new release, please use the command:

./install.pl --disable

ENDscript uses some databases: these must be installed, and up to date, on your system. Those databases are:

Databases used with BLAST:

Those database files must be deposited in $BLAST_DB. Every database deposited here will appear in the list of databases, inside the BLAST box in ENDscript. Please do not forget to run the program formatdb after each update of the fasta files.

• pdbaa, swissprot retrieved from nih
• Complete genomes retrieved from expasy

Pdb and related databases:

It is possible to retrieve the pdb files when they are needed from a remote site using different protocols, however if you want to install ENDscript you'll have to install the pdb locally. The pdb may be retrieved (updated each week) from rcsb.
ENDscript needs a database of dssp files, and of spdb cleaned files (just for better performance, as very often we need a lot of dssp or cleaned db files). This database may be updated using the script pdb2dssp.pl found in the bin directory.

Link between pdb and swissprot

ENDscript needs to know which pdb ID corresponds to which Swissprot ID. This is possible only with the file pdbtosp.txt you may retrieve from expasy. You should retrieve this file regularly, as it is very often updated. This file must be deposited in the directory $ROOTDIR/html/ENDscript/