Bioscape Installation

---

Please note that this documentation covers an unreleased product and is for internal use only.

---

Installation

Bioscape consists of three separate applications which must be combined to provide all the facilities of a functional Bioscape installation:

• The administrative application: bsadmin
• The text-indexing application: bsindex
• The Web front-end application: bsweb

Before installing, it is necessary to consider the dependencies listed in the section given below. Precise information about installing the dependencies is not provided in this document, and it is recommended that you make use of your system's package management tools, perhaps installing Bioscape itself from suitable packages, in order to save time and effort working through the installation process manually. However, for those interested in installing Bioscape from the source code distribution of each application, the procedure is given below.

Installation from Source Code

First, nominate a common directory to hold the Bioscape application directories. For example:

/home/bioscape/apps

Then, acquire each application's source code distribution (details to be provided) and unpack the archives in this common directory:

cd /home/bioscape/apps
tar zxf bsadmin-x.y.tar.gz
tar zxf bsindex-x.y.tar.gz
tar zxf bsweb-x.y.tar.gz

Since these applications contain Python libraries, it is important to configure the environment so that they may be accessed by Python. This may be done by creating a short configuration file resembling the one provided as docs/configuration/env.sh in the bsadmin distribution and then incorporating it into your environment within a .bashrc or equivalent file as follows:

source /home/bioscape/apps/bsadmin/docs/configuration/env.sh

Dependency Configuration

For some of the dependencies, even with pre-installed packages, you will need to do some preparatory work in order to use Bioscape. Some brief details of this work are given below.

See also the Bioscape Dependencies page for a list of the dependencies.

Installation of Dependencies

The docs/dependencies/download.sh file in the bsadmin distribution provides some commands which should be able to download the source distributions of various dependencies. This file or a modified version of it could be run in a nominated directory which would then hold copies of the dependencies' archive files.

The docs/dependencies/build.sh file in the bsadmin distribution provides some commands which could be run to build each of the dependencies from the previously downloaded archive files.

PostgreSQL

It may be necessary to initialise a "database cluster" for Bioscape. This is typically done using commands such as the following:

mkdir -p /home/bioscape/pgsql
initdb -D /home/bioscape/pgsql

Setting the PGDATA environment variable to the directory given in the above commands will save you the effort of specifying it later with other PostgreSQL-related commands. This variable is mentioned in the env.sh file referenced above.

In order to get improved performance from PostgreSQL, consider replacing the postgresql.conf file in the database cluster with the version found in the docs/database directory of the bsadmin distribution.

Since Bioscape only requires a single database to be created, it is also possible to create this database within an existing cluster. However, there may be issues with the database encoding or locale which cause errors when running the bioscape_configure.py program. Where an existing cluster has no active databases, it can be appropriate to drop and recreate the cluster with an appropriate configuration, such as in this example (employing Debian-related techniques):

pg_dropcluster --stop 8.3 main
pg_createcluster --locale C --start 8.3 main

(Here, a version of 8.3 is meant to correspond with the installed version of PostgreSQL. Note that pg_dropcluster and pg_createcluster are Debian-specific tools, however.)

Configuration

Before use, the distribution must be configured according to the environment in which the software will operate. This is done most conveniently by running the configuration program in the bsadmin directory:

python scripts/bioscape_configure.py

The configuration program takes the bioscape.cfg.in template and produces a specific bioscape.cfg configuration file. An alternative approach is to copy bioscape.cfg.in to bioscape.cfg and to edit the file manually.

Once the bioscape.cfg file has been produced, it may be left in the bsadmin directory, or it can be copied or moved to your home directory; for example:

mv bioscape.cfg /home/bioscape

Database Configuration

The database support must also be configured, preferably using the database configuration program in the bsadmin distribution:

python scripts/bioscape_dbconfigure.py

Each of the modules (or packages) requiring database support can be listed, and the specific table and data definitions can be prepared and invoked using the database configuration program.

Quick Start

Use the quick start program - provided in the bsindex distribution - in order to initialise Bioscape as quickly as possible:

python scripts/bioscape_quickstart.py --init

On a modern, multi-core system, it is recommended that updates be performed as follows:

python scripts/bioscape_quickstart.py --update-parallel

Otherwise, use the plain update method:

python scripts/bioscape_quickstart.py --update

Web Interface

The Web interface to Bioscape - provided in the bsweb distribution - can be run as a stand-alone service or installed as a CGI program; the CGI-based solution is recommended for public deployment of the interface. Before the interface can be accessed, a resource preparation script must be run in the bsweb directory:

python tools/prepare.py

To deploy a stand-alone service for testing purposes, run the appropriate script:

python scripts/bsweb_simple.py

Installing the Web interface as a CGI program involves editing the scripts/bsweb.cgi file to ensure that the environment settings are appropriate, and then copying that file and the scripts/bsweb_cgi.py file to your server's cgi-bin directory (or equivalent).