Bioscape Configuration

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

After installation, a degree of configuration is necessary before the system can be used.

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

Bioscape

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

If the software has been installed using system packages, run the program as follows:

bioscape_configure.py --init

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

Initialising the Database

To initialise the database according to the configuration, run the configuration script with the appropriate option as follows:

python scripts/bioscape_configure.py --init-db

Or, if the software has been installed using system packages, run the program as follows:

bioscape_configure.py --init-db

On some systems, it may be necessary to run this command as a privileged user, such as one which manages the database. For example:

sudo -u postgres bioscape_configure.py --init-db

This creates a database and a database user for Bioscape.

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

If the software has been installed using system packages, run the program as follows:

bioscape_quickstart.py --init

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

bioscape_quickstart.py --update-parallel

Otherwise, use the plain update method:

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 scripts/bsweb_prepare.py

This script is run automatically if the software is installed using system packages.

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

python scripts/bsweb_simple.py

If the software has been installed using system packages, run the program as follows:

bsweb_simple.py

CGI-based Web Interface

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