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 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

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 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 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:

Test your Python installation and virtual directory

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

Go to http://localhost/biocase

You should already see something like this:

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 http://localhost/biocase/utilities/testlibs.cgi

You should see something like this:

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. Please read the Metakit paragraph below.

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.

Metakit library

/!\ The metakit library is a special case. It is bundled with the BPS2 but unfortunately depends upon your OS. The BPS2 setup.py script will detect your OS and select the appropiate metakit lib for you.

In case you did not use the setup.py script you can also do so manually depending upon your OS metakit. All the metakit files should be inside /biocase/lib/biocase/configtool/utilities/metakit/

Windows For Windows the metakit lib comes as a DLL and should be named Mk4py.dll. Please rename the DLL that matches your python version in to Mk4py.dll. So for example if you use Python2.4 on Windows do the following: 

C:\..\biocase>cd lib/biocase/configtool/utilities/metakit/
C:\..\metakit>ren Mk4py_py24.dll Mk4py.dll

Linux For Linux the metakit lib comes as a shared object file and should be named Mk4py.so. Please rename the DLL that matches your python version and OS into Mk4py.so. If for example you are using Python2.4 on Mac OSX do the following: 

biocase$ cd lib/biocase/configtool/utilities/metakit/
metakit$ mv Mk4py_macosx.so Mk4py.so

For other Unix derived systems please do accordingly.

Update the BioCASe Provider Software

From time to time there are new releases of the BioCASe Provider Software. These releases normally include bug fixes and sometimes new features. Following the maxim of "what works should not be touched" 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 through 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 double 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...

Installation (last edited 2008-04-21 13:43:42 by MarkusDoering)