Difference between revisions of "Bioscape Installation"

From irefindex
(→‎Quick Start: Fixed command options.)
m (Moved note to a separate page.)
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
----
+
{{:Bioscape Status}}
 
 
'''Please note that this documentation covers an unreleased product and is for internal use only.'''
 
 
 
----
 
  
 
== Installation ==
 
== Installation ==
Line 33: Line 29:
 
  source /home/bioscape/apps/bsadmin/docs/configuration/env.sh
 
  source /home/bioscape/apps/bsadmin/docs/configuration/env.sh
  
== Dependency Configuration ==
+
=== Installation of Dependencies ===
  
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 the [[Bioscape Dependencies]] page for a list of the dependencies.
 
 
See also the [[Bioscape Dependencies]] page for a list of the dependencies.
 
 
 
=== Installation of Dependencies ===
 
  
 
The <tt>docs/dependencies/download.sh</tt> file in the <tt>bsadmin</tt> 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 <tt>docs/dependencies/download.sh</tt> file in the <tt>bsadmin</tt> 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.
Line 45: Line 37:
 
The <tt>docs/dependencies/build.sh</tt> file in the <tt>bsadmin</tt> distribution provides some commands which could be run to build each of the dependencies from the previously downloaded archive files.
 
The <tt>docs/dependencies/build.sh</tt> file in the <tt>bsadmin</tt> distribution provides some commands which could be run to build each of the dependencies from the previously downloaded archive files.
  
=== PostgreSQL ===
+
For some of the dependencies, even with pre-installed packages, you will need to do some preparatory work in order to use Bioscape. This is documented on the [[Bioscape Configuration]] page.
 
 
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 <tt>PGDATA</tt> 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 <tt>env.sh</tt> file referenced above.
 
 
 
In order to get improved performance from PostgreSQL, consider replacing the <tt>postgresql.conf</tt> file in the database cluster with the version found in the <tt>docs/database</tt> directory of the <tt>bsadmin</tt> 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 <tt>bioscape_configure.py</tt> 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 [http://wiki.debian.org/PostgreSql Debian-related] techniques):
 
 
 
<pre>
 
pg_dropcluster --stop 8.3 main
 
pg_createcluster --locale C --start 8.3 main
 
</pre>
 
 
 
(Here, a version of 8.3 is meant to correspond with the installed version of PostgreSQL. Note that <tt>pg_dropcluster</tt> and <tt>pg_createcluster</tt> 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 <tt>bsadmin</tt> directory:
 
 
 
python scripts/bioscape_configure.py
 
 
 
The configuration program takes the <tt>bioscape.cfg.in</tt> template and produces a specific <tt>bioscape.cfg</tt> configuration file. An alternative approach is to copy <tt>bioscape.cfg.in</tt> to <tt>bioscape.cfg</tt> and to edit the file manually.
 
 
 
Once the <tt>bioscape.cfg</tt> file has been produced, it may be left in the <tt>bsadmin</tt> 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 <tt>bsadmin</tt> 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 <tt>bsindex</tt> 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 <tt>bsweb</tt> 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 <tt>bsweb</tt> 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 <tt>scripts/bsweb.cgi</tt> file to ensure that the environment settings are appropriate, and then copying that file and the <tt>scripts/bsweb_cgi.py</tt> file to your server's <tt>cgi-bin</tt> directory (or equivalent).
 
  
 
[[Category:Bioscape]]
 
[[Category:Bioscape]]

Latest revision as of 13:36, 14 July 2010

NoteNotePlease 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

Installation of Dependencies

See the Bioscape Dependencies page for a list of the 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.

For some of the dependencies, even with pre-installed packages, you will need to do some preparatory work in order to use Bioscape. This is documented on the Bioscape Configuration page.