Installation guide

BioCASe Provider Software v. 2.3.0

/!\ Notice: This is the first document to read in order to proceed with the BioCASe Provider Software product installation.

The latest version of this document can always be found at [WWW] http://ww3.bgbm.org/bps2/Installation


Installing and running the BioCASe Provider Software

This document describes the steps that are required to setup and configure your system to run the BioCASe Provider Software.

Required configuration

The BPS (BioCASe Provider software) runs on the following platforms

Getting the software package and extracting it

The distribution is provided as a simple archive called provider_software_2.xx.tar.gz to be extracted into wherever you want on your server. To extract the contents in Windows you can use Winzip for example.

For example uncompress it into c:\biocase.After decompressing it you will see the next structure

folders_v2.gif

Alternatively you can connect to the subversion repository directly and obtain the latest stable version like this:

svn export http://ww2.biocase.org/svn/bps2/branches/stable

Setting up a public folder in your web server

The public part of the provider software that must be configured in your web server is the www folder. You should always make this folder public using a virtual directory. This means that you should never install the software under the default root folder of your web server. Doing so will compromise your server security and will allow people to see your configuration files whixh include passwords.

So if you install your software in C:\biocase then the folder that must be published with a Virtual directory is C:\biocase\www and will be accessible trough [WWW] http://localhost/biocase/

Of course this is just an example, install it wherever you want and give it the name you like.

Installing Python

First of all, you will have to download the Python program. Go to [WWW] http://www.python.org/download/ and download the latest 2.4.x version of Python available for your operating system. At the time of writing, the latest version of Python is "2.4.2" and the BioCASE software is known to work correctly with that version. When you have finished downloading Python you have to install it.

Install Python on Windows:

In Windows you will just use the windows installer that is very easy, follow our explanation below. For Unix please read the installation instructions. We recommend that in Windows you install Python in the proposed location, as you might have to modify some BioCASE scripts.

Install Python on Unix:

In Unix you don't have to care about this, just install Python the way it is described in its installation instructions.

Adapt BPS scripts to your OS: The python CGI scripts contain a she-bang line in their beginning that contains the path to your python interpreter. We provide a script in the tools folder that you should run once to adapt these lines automatically and changes the file permissions as required.

If you follow this instruction and make use of the setup.py script later on you can skip this step. But if you would like to do a manual installation, please run the following adaption script:

%> cd biocase/tools
%> python adapt2unix.py

Configure your Webserver for Python CGIs

In order to use Python as a scripting language for CGIs, you have to tell your webserver where to find your Python installation and how to identify a Python CGI script. The procedure to do so is very much dependent upon your operating system, on the kind of webserver and how you installed your webserver.

Using Python with IIS

There are several tutorials on Internet about how to configure IIS for Python scripts check:

If you have Windows 2003 and IIS 6 then it is a little bit more complicate because of some bugs in the administration tool, check here and good luck:

We have managed to make it work so do not hesitate to contact us if you do not manage to make it work.

You should also set index.html to the list of default documents if it is not allready added (virtual directory; properties; documents; default documents).

Using Python with Apache

If you have an already existing installation of Apache, ask the IT responsible person for help. In case you have a fresh installation, it should be sufficient to add the following lines of code to the end of the httpd.conf configuration file in your Apache installation:

AddHandler      cgi-script .cgi
Alias           /biocase "c:/biocase/www"

<Directory "C:/biocase/www">
   Order Deny,Allow
   Allow from all
   Options +ExecCGI
   AllowOverride All
</Directory>

Adjust the path C:/biocase/www to point your BPS folder (see above). You need this to allow Apache to execute CGIs in your wrapper instance folder.

Remember to restart Apache so that the changes take place.

Run the setup file to configure the software for your environment

Go to your software installation folder, for example C:\biocase. You will find there a file called setup.py

This file will prepare the software to run in your environment (Operating System, paths, etc.). It is also used for updating the software as you will read later.

Just run this Python script and follow the instructions. In Windows you can doble click on the file and it will open in a terminal window. In Unix it should be also rather easy as long as Python is install on your computer.

The entrance of the script will looks like this:

setup_py.gif

Test your Python installation and virtual directory

Now you will test your Python installation and install other software that is needed.

Go to [WWW] http://localhost/biocase

You should already see something like this:

main_page.gif

If you do not see something like this probably you have a problem with the configuration of Python for your Web server. Go back and check the configuration.

Install Third Party Packages

Now that Python is running as a CGI the next step is to install and test other necessary libraries. In the main web page were you were already click on the Utilities box.

This utilities page is there for helping you debugging problems with the software installation. We will skip most of the text. Click on the Test your Python CGI installation Part 2 link. You can optionally go directly to it at [WWW] http://localhost/biocase/utilities/testlibs.cgi

You should see something like this:

libraries.gif

As you see things that are in red are mandatory libraries to install, in orange depends on your database and in green is Ok.

/!\ The metakit library is a special case. If you were using the setup-py script to adapt your environament, and you should have!, then you probably do not have to worry about this. Only in the case that you are not installing the software in Windows, Linux or MAC OS X (for example Solaris), you will have to care to adapt the metakit library. For Solaris users, for example, go to:

%>cd /biocase/lib/biocase/configtool/utilities/metakit/
%>mv Mk4py.so Mk4py_linux.so

FOR SOLARIS:
%>mv Mk4py_solaris8Sparc.so Mk4py.so


/!\ Remember that this step is only for NON Windows, Linux and MAC OS X users.

You will have to go one by one downloading the necessary libraries and installing them.

The link to the official web page is provided on the right. We recommend you to open in a different window the links, download the file, install it, go back to this page and refresh to see that the library has been correctly installed. At the end you should not see anything in red.

The installation of the libraries depends on your operating systems.

Sometimes it may be difficult to find the correct file to download in the different library sites. If you do not manage to find them please contact us and we will help you.

Graphviz: The graphviz binaries are used to create graph images for your configured database structure. This package is not required but makes the configtool easier to use. The external dot binary of the open source graphviz package is being used for this and needs to be executable by the webserver. You will have to tell the BPS2 where to find the executable. Please do this using the system admin part of the configuration tool in the next chapter. Alternatively you can manually edit the entry graphviz_dot of the file configuration/configtool/.configuration. Please set it to the absolute path to the dot binary of graphviz or leave it None if you dont want to use graphviz.

Notice: We ask you to download the libraries from external sites because in this way you will always get the latest version and you can find related information. Also some licenses, although free to use, do not allow us to bundle the software in another distribution.

Update the BioCASe Provider Software

From time to time there are new releases of the BioCASe Provider Software. These releases include normally bug fixes and sometimes new features. Following the maximum of that "what works should not be touch" we kindly ask you to only update your BioCASe provider Software if something is not working with you and there is a newer version available. If there is any critical update with security implications we will contact you and ask you to update the software (very rare).

/!\ Only use this procedure to update from the BioCASe Provider software version 2 or higher. If you have an older version you will have to do it manually. You can contact us for more information.

To learn how to update the software we will do it trough an example. You have installed the BPS2 version 2.01 in C:\biocase and you have downloaded the version 2.2.0 into C:\tmp\provider_software_2.2.0.zip. We uncompress the contents of this folder so that it creates C:\tmp\biocase. If you go to this folder you will a file called setup.py. Execute it by doble clicking on it or typing it.

Now you are inside the setup script, you can follow the instructions. Start saying yes to the question if you want to update...

last edited 13.10.2005 09:56:54 by MarkusDoering