StackPACK 2.2.1 Installation Instructions

----------------------------------------------------------------------

Installation Instructions for Updating An Existing
stackPACK Installation StackPACK v2.2.1

----------------------------------------------------------------------

StackPACK: StackPACK version 2.2.1

Platforms: HP Tru64 UNIX 4.0F and 5.1A

Release date: February 2003

This document describes the procedures for updating an existing
stackPACK v2.1.1 installation.

----------------------------------------------------------------------

TABLE OF CONTENTS

I. CONVENTIONS
II. SYSTEM REQUIREMENTS
III. PRE-INSTALLATION PROCEDURES
IV. UNINSTALLING EXISTING stackPACK COPIES
V. UNPACKING THE DISTRIBUTION
VI. INSTALLING THE DISTRIBUTION
VII. POST-INSTALLATION PROCEDURES
VIII. TESTING THE stackPACK INSTALLATION
IX. CUSTOMIZING YOUR stackPACK CONFIGURATION
X. TROUBLESHOOTING
XI. CONVERTING stackPACK v2.1.1 PROJECTS TO stackPACK V2.2.1 FORMAT

----------------------------------------------------------------------

I. CONVENTIONS

The following conventions are used in these installation instructions:

- <text in angle brackets> System-specific information. Replace the
text in the brackets with information
relevant to your system,e.g.
stackpack-2.2.1-<date>.tar.gz.

- [text in square brackets] Denotes default location or information.

II. SYSTEM REQUIREMENTS

1. Supported platforms

Hardware OS Version
----------------------- -----------------
HP Tru64 UNIX 4.0F
HP Tru64 UNIX 5.1A

2. RAM
Minimum Requirements: 256MB
Recommended Requirements: The user requirements depend on
the size of the datasets and clusters to be processed. Increased
RAM significantly increases stackPACK performance.

3. Disk space
Minimum Requirements: stackPACK requires 50MB to install and 75MB
to run.
Recommended Requirements: The user requirements depend on the size
of the datasets and clusters to be processed. In addition to the
minimum requirements, stackPACK requires 5x the datasize to run.

4. Required third-party software

Software Version Location
--------------------- ------------------------- ----------
d2_cluster and CRAW(1) latest Academic: Biotique Systems: bpoh@biotiquesystems.com
Academic: University of Houston: bsmalley@uh.edu
Commercial: Electric Genetics: support@egenetics.com

Phrap and Cross_Match 1996 or 1999 Academic: http://www.phrap.org
Commercial: http://www.codoncode.com/
Commercial: http://www.geospiza.com/products/index.htm

RepBase user's choice Academic: http://www.girinst.org/index.html
(optional) Commercial:http://www.geospiza.com/products/index.htm
Commercial: http://www.girinst.org/index.html

RepeatMasker April 1999 or newer Academic: http://repeatmasker.genome.washington.edu/
(optional) Commercial: http://www.geospiza.com/products/index.htm

Apache 1.3 or newer http://www.apache.org

Python(2) python2-2.2.1 http://www.python.org/2.2.1/

MySQL(3) 3.23.27 or newer http://www.mysql.com/downloads/mysql-3.23.html
- Server
(MySQL 3.23.xx)
- Libraries and Header
files for development
(MySQL-devel-3.23.xx)
- Client programs
(MySQL-client-3.23.xx)

MySQLdb (4) 0.9.1 http://www.mysql.com/downloads/api-python.html
(MySQL-python-0.9.1)

NOTE:
(1) Commercial customers do not need to obtain d2_cluster and CRAW
separately - it is included in the stackPACK distribution file.
Academic customers: Please state clearly for which of the supported
platforms you would like precompiled d2_cluster and CRAW binaries
for and use the following as the e-mail subject: "Precompiled
d2_cluster and CRAW for <your platform of choice>."

(2) Use Python-2.2.1 and compile using the --with-threads option.

(3) Although MySQL binaries can be obtained from elsewhere, we
strongly recommend the binaries available from
http://www.mysql.com/downloads/mysql-3.23.html as they are best
supported.
MySQL-devel-3.23.xx and MySQL-client-3.23.xx are required for
installation of MySQLdb

(4) In order to build MySQLdb it may be necessary to manually edit
setup.py to correctly specify the MySQL and Python header and
library files as described in the README file provided in the
archive.

III. PRE-INSTALLATION PROCEDURES

This installation assumes a working knowledge of Unix and MySQL.

1. Ensure that you have upgraded your operating system to use one of
the supported platforms.

2. Ensure that you have installed, configured and tested the web
server, MySQL, MySQLdb (MySQL-python) and Python v2.2.1.

3. Make the following symlinks:

> ln -s /usr/local/bin/python2.2 /usr/local/bin/python2
> ln -s /usr/local/bin/python2.2 /usr/bin/python2

4. You will need the following information in order to proceed with
your stackPACK installation:

- The stackPACK hostname for the general stackPACK installation. Ensure
that you use the fully qualified host domain name, also referred to
as fqdn, e.g. use '<host>.egenetics.com'instead of just '<host>'.

- The stackPACK installation target: default /usr/local/stackpack

- The hostname for the stackPACK Mail (SMTP) server. This requires
the fully qualified host domain name, also referred to as fqdn.

- The location of your web server html root: usually
/home/httpd/html or /var/www/html.

- The location of your web server cgi-bin root: usually /home/httpd/cgi-bin
or /var/www/cgi-bin.

- The username and password of a MySQL account with privileges to
create new MySQL users.

- The MySQL server hostname of the above MySQL account that has these
user creation privileges. Depending on how MySQL was set up, this
hostname could be referred to as either 'localhost' or the actual
hostname, '<host>.domain'. Please ensure that the appropriate name
is selected.

5. MAKE A LIST OF ALL YOUR stackPACK V2.1.1 PROJECT NAMES THAT YOU
WISH TO CONVERT TO stackPACK V2.2.1 FORMAT. Projects that have
been converted can be viewed, output and modified in
stackPACK v2.2.1. Please refer to section XI, Converting
stackPACK v2.1.1 projects to stackPACK v2.2.1 format, and the
command line user manual for details on how to convert a project.

IV. UNINSTALLING EXISTING stackPACK COPIES

The installation script tests for existing stackPACK copies installed
in the default /usr/local/stackpack location. StackPACK v2.2.1 will
not install if existing copies are found in this location and users
have to uninstall these copies.

NOTE: If an existing stackPACK copy has been installed in a
non-default location, the installation script will proceed
and you may end up with a non-working stackPACK installation.
Existing stackPACK copies in non-default locations should thus
also be removed.

The following procedures remove your existing stackPACK installation.

1. Move the third-party dependencies, phrap, cross_match, the repeat
database, base_repeat.seq, and any other programs such as
RepeatMasker that are not included in the distribution package to
a temporary location:

> mv <stackpack install dir>/supporting/repeat.seq <temporary dir>
> mv <stackpack install dir>/bin.ext/phrap <temporary dir>
> mv <stackpack install dir>/bin.ext/cross_match <temporary dir>
> mv <stackpack install dir>/bin.ext/d2_cluster <temporary dir>
> mv <stackpack install dir>/bin.ext/enc_db <temporary dir>
> mv <stackpack install dir>/bin.ext/craw <temporary dir>

NOTE: You may have to log in as root to move some of these files.

NOTE: We recommend that you obtain new copies of d2_cluster, enc_db
and CRAW from the locations specified in step 4 of section II,
System Requirements. Commercial users do not need to obtain new
copies of d2_cluster, enc_db and CRAW as these will be included
in the stackPACK distribution file.

2. Move the stackpack and odbc.ini configuration files in the
<stackPACK config dir> to a temporary location. The default
configuration file location is /etc.

> mv <stackpack config dir>/stackpack <temporary dir>
> mv <stackpack config dir>/odbc.ini <temporary dir>

These files may be needed later.

NOTE: You may have to log in as root to move these files.

3. Delete the following directories:

> rm -rf <stackpack install dir>
> rm -rf <webserver cgi-bin directory>/stackpack
> rm -rf /stackpack

Use the stackpack configuration file, which you had moved to a
temporary location in step 2 to determine the exact location of
these directories. The default location of the stackPACK install
directory is /usr/local.

NOTE: You may have to log in as root to delete some of these files.

V. UNPACKING THE DISTRIBUTION

1. Copy the stackPACK distribution file to a temporary directory of
50MB.

2. Unpack it with:
> gzip -d stackpack-2.2.1-<date>.tar.gz
> tar xvf stackpack-2.2.1-<date>.tar

3. Type ls in order to display the contents in the temporary directory.
The directory should contain the following:
- stackpack-2.2.1-<date>
- stackpack-2.2.1-<date>.tar

4. Move to the stackpack-2.2.1-<date> directory with:
> cd stackpack-2.2.1-<date>

5. Type ls in order to display the directory contents. The directory
should contain the following:
- cgi-bin/ The cgi scripts required for the web interface
- etc/ The stackPACK configuration files
- html/ The html files required for the web interface
- setup.sh The stackPACK installation script
- stackpack/ The main stackPACK installation tree

VI. INSTALLING THE DISTRIBUTION

1. Log in as root. Root access is required to install certain parts of
stackPACK - you may thus require assistance from your systems
administrator if you do not have root access.

2. Ensure that you are in the stackpack-2.2.1-<date> directory.

3. Execute the setup script by typing the following command:
> sh setup.sh

This script will test for MySQL and Python dependencies, for old
stackPACK installations and will configure your new stackPACK
installation. A number of questions need to be answered in order
for configuration to occur. The default answers to the questions are
shown in square brackets - if these answers are appropriate, simply
hit return. Otherwise, type the correct information at the prompt, and
hit return. You will be given the opportunity to confirm or modify any
of your selections at the end of the script.

SECTION A -- GENERAL INSTALLATION PARAMETERS:

stackPACK hostname: [local.domain]

The fully qualified host domain name of the system on which you wish
to install stackPACK, otherwise known as the fqdn. The webserver will
also be installed on this host.

stackPACK installation target: [/usr/local/stackpack]

The default directory in which stackPACK will be installed. StackPACK
can however be installed in any other location. For the remainder of
this document the stackPACK installation target will be referred to as
the <stackpack install dir>.

If you do not install stackPACK in the default location:
- Ensure that you/root have permission to write to the directory you
wish to install in.
- Ensure that you set your PATH and LD_LIBRARY_PATH environment
variables to use the non-default location. Please refer to numbers
1 and 2 of section VI, Post-Installation Instructions, for further
details.
- Ensure that your LD_LIBRARY_PATH environment variable is set in the
Apache httpd.conf file. Please refer to number 3 of section VII,
Post-Installation Instructions, for further details.

SECTION B -- stackPACK WEB INTERFACE

Install WWW interface? (Y/n)

Answer 'Y' if you want the stackPACK web interface to be installed.
Yes ('Y') is the default option and can be selected by simply hitting
enter. If you answer 'n' at this point, only the command-line
stackPACK tools will be installed.

Mail (SMTP) server hostname: [local.domain]

The fully qualified host domain name of the system, otherwise known as
the fqdn, of the stackPACK SMTP mail server. This host is also used by
the web interface as a mail server for sending status updates to users.

Directory where stackPACK's HTML interface files
will be installed: [/var/www/html/stackpack]

The directory where the HTML files for the stackPACK web interface will
be installed.

URL where "/var/www/html/stackpack" will appear on
your server:[/stackpack]

If a non-default location was used to install the stackPACK html files,
it must be reflected in the URL.

Directory where stackPACK's CGI scripts will be
installed:[/var/www/cgi-bin/stackpack]

The directory where the cgi-bin scripts for the stackPACK web interface
will be installed.

URL where "/var/www/cgi-bin/stackpack" will appear
on your server:[/cgi-bin/stackpack]

If a non-default location was used to install the stackPACK cgi-bin
files, it must be reflected in the URL.

SECTION C -- DATABASE CONNECTIVITY

MySQL server hostname: [local.domain]

The MySQL server hostname of a MySQL account with user creation
privileges. Depending on how MySQL was set up, this hostname could be
referred to as either 'localhost' or the actual hostname,
'<host>.domain'. Please ensure that the appropriate name is selected.

If you wish to install the MySQL database on a different host to
stackPACK, you must ensure that the database host has a user with
creation privileges that allows the stackPACK host to create databases
or projects on it. This can be achieved by running the following
command from the database host:
GRANT ALL PRIVILEGES ON *.* TO '<stackpack@host.domain>' IDENTIFIED BY 'stackpack' WITH GRANT OPTION;

Enter a MySQL account on the above MySQL server that has
user creation privileges from the current host:[root]

The name of a MySQL account that has privileges to create new users.

Please enter MySQL password for root:

The password for the above-mentioned account.

Testing database connectivity... DONE!

Please enter stackPACK MySQL account name: [stackpack]

The name of the MySQL account that will be created to give stackPACK
access to the MySQL database.

Please enter stackPACK MySQL account password: [stackpack]

The password of the MySQL account through which stackPACK gains
access to the MySQL database.

4. Upon completion of the questions, the script will display all the
answers you have given. You may modify these answers at this point by
selecting the relevant number and entering the modified details. Once
you have confirmed all answers by entering 'Y', the script will go
ahead with the stackPACK installation.

--------------------------------------------------------------------
To modify, select one of the following:
--------------------------------------------------------------------
1 - stackPACK hostname: [local.domain]
2 - stackPACK installation target: [/usr/local/stackpack]
3 - Install WWW interface: [yes]
4 - Mail (SMTP) server hostname: [local.domain]
5 - Webserver HTML directory: [/var/www/html/stackpack]
- HTML URL: [/stackpack]
6 - Webserver CGI directory: [/var/www/cgi-bin/stackpack]
- CGI URL: [/cgi-bin/stackpack]
7 - MySQL server: [localhost]
8 - MySQL account with user creation privileges: [root]
- Password for root: [not displayed]
9 - stackPACK MySQL user account: [stackpack]
10 - stackPACK MySQL user password: [stackpack]
--------------------------------------------------------------------
Y - Accept above values and continue installation
N - Cancel installation
--------------------------------------------------------------------

Please enter your choice:

NOTE: If you modify the HTML or cgi-bin file locations in options 5
and 6, it should be reflected in the HTML and cgi-bin URLs
respectively. If you modify the MySQL server in option 7, it
should be reflected in the MySQL account and password with
user creation privileges in option 8.

5. Once you have accepted all the options the installation proceeds as
follows:

Installation starting:

Creating stackpack user... DONE!
Checking for existing stackpack system database... DONE!
Installing main stackpack distribution... DONE!
Installing web interface html files... DONE!
Installing web interface CGI files... DONE!
Installing configuration files... DONE!
Running /sbin/ldconfig... DONE!
Setting up file and directory permissions... DONE!
Creating /var/www/html/stackpack/orbit and setting up permissions... DONE!

setup.sh has installed files in the following locations:

/var/www/html/stackpack
/var/www/cgi-bin/stackpack
/etc/stackpack
/etc/odbc.ini
/etc/odbcinst.ini
/etc/orbit.rc
/etc/.orbitrc

Please complete the stackPACK installation according to the
installation instructions.

VII. POST-INSTALLATION PROCEDURES

After completion of the installation script, complete the following
tasks before attempting to run stackPACK.

1. Ensure that each user's PATH environment variable has the <stackpack
install dir>/bin added to it:

C-shell users, for example: setenv PATH ${PATH}:/usr/local/stackpack/bin
Bash-shell users, for example: export PATH=$PATH:/usr/local/stackpack/bin

2. Ensure that each user's LD_LIBRARY_PATH environment variable has
/usr/local/lib:<stackpack install dir>/lib added to it:

C-shell users, for example:
setenv LD_LIBRARY_PATH /usr/local/lib:/usr/local/stackpack/lib
Bash-shell users, for example:
export LD_LIBRARY_PATH=/usr/local/lib:/usr/local/stackpack/lib

3. Set the LD_LIBRARY_PATH in the Apache httpd.conf file as follows:

SetEnv LD_LIBRARY_PATH <stackpack install dir>/lib:/usr/lib:/usr/local/lib
Remember to restart Apache to activate this environment variable.

4. Edit the LD_LIBRARY_PATH in the [STACKPACK] section of the /etc/stackpack
configuration file as follows:

LD_LIBRARY_PATH=<stackpack install directory>/lib:/usr/local/lib

5. Move the enc_db, d2_cluster, craw, phrap, cross_match and repeat
database dependencies that had been moved to a temporary location in
step 1 of section IV, Uninstalling Existing stackPACK Copies, as
follows:

mv <temporary dir>/base_repeat.seq <stackpack install dir>/supporting/
mv <temporary dir>/phrap <stackpack install dir>/bin
mv <temporary dir>/cross_match <stackpack install dir>/bin
mv <temporary dir>/d2_cluster <stackpack install dir>/bin
mv <temporary dir>/enc_db <stackpack install dir>/bin
mv <temporary dir>/craw <stackpack install dir>/bin

NOTE: The standard configuration on stackPACK is for the latest
(1999) phrap and cross_match. If you would like to use the
older version of phrap (1996), some parameter settings need
to be changed. Please see no. 7 of section VIII, Customizing
Your stackPACK Installation, for further details.

NOTE: Phrap has limits of 64K bases for each sequence, and 64K
sequences per cluster. Phrap can be compiled with a
.longreads or .manyreads option that allows assembly of
sequences with more than 64,000 bp or clusters with more than
64,000 sequences. These options can only be used with PHRAP
v 0.990319.

NOTE: We recommend that you obtain new copies of d2_cluster, enc_db
and craw.

6. You may use any masking database to mask your data with by
replacing the masking database supplied with stackPACK,
base_repeat.seq, found in the default location of
<stackpack install dir>/supporting/, with the masking database of
your choice.

The masking database supplied with stackPACK contains the following:
- Common vector sequences, distributed by NCBI
- Other potential contaminants such as rodent, mitochondrial and
ribosomal DNA.

7. If you wish to use RepeatMasker for the masking step, you can
install it anywhere as long as the location is reflected in the
/etc/stackpack configuration file.

8. If necessary, customize the configuration of your stackPACK
installation by verifying whether /etc/stackpack, /etc/odbc.ini
and /etc/odbcinst.ini files contain the desired settings. See
section IX, Customizing your stackPACK Configuration, for more
details on these files. If you want the new v2.2.1 /etc/stackpack
configuration file details and parameters to correspond to the old
v2.1.1 <stackpack config dir>/stackpack configuration file details
and parameters, use the stackpack configuration file which you had
moved to a temporary location in step 2 of section IV,
Uninstalling Existing stackPACK Copies, to compare the two files.

9. Ensure that the MySQL logging is switched off. During data
processing stackPACK makes many connections to the database, and
if the log file is not switched off you may run out of disk space.
It should be switched off by default.

StackPACK should now be installed on your system. You can access it
either via the command line or through the web interface at
http://<stackpack hostname>/stackpack/

Please continue to the following sections for details on testing and
customization of your stackPACK installation.

VIII. TESTING THE stackPACK INSTALLATION

1. StackPACK processing via the web interface:

- To test the database connectivity, go to
http://<stackpack hostname>/stackpack, and click on
WebProjectManager. An empty project table should be displayed if
the database connectivity is properly set up.

- To test whether the programs are working correctly via the web
interface go to http://<stackpack hostname>/stackpack, and click
on WebPipe. Complete the WebPipe data submission forms in order to
submit a clustering job. Please fill in all the details:
o Project Name Enter a brief one-word alphanumeric project
name, e.g. Test_alt
o Owner Enter your full e-mail address.
o Description Enter a one-line project description for your
reference.
o Data Format Select 'Mixed or unknown FASTA Format'.
o Next Click on 'Next' to move to the next step.
o Data File Enter the name of the input data file. Use the
browse option to specify the location of the
input data file. A test datafile is in
<stackpack install dir>/doc and is called
alt_splice.seq
o Upload Click on "Upload" to initialize the clustering
process.

This dataset will be processed quickly and you should receive an e-mail
upon project submission as well as upon project completion. Verify that
all programs executed properly by reviewing the log sent upon project
completion. The log contains details of each step in the pipeline,
including parameter settings and any errors that may have occurred.
If the entire pipeline and thus the project fails to complete, the
log report is still e-mailed to the user.

2. StackPACK processing via command line:
To test whether the programs are working correctly via the command
line, please carry out the following instructions:

- Create a stackPACK project with the following command:
stack_ProjectManager -create Test_alt2 testing <project owner>

- Import the sequences from the input data file into stackPACK's
database with the following command: stack_ImportFasta
Test_alt2 <stackpack install dir>/doc/alt_splice.seq GUESS

- Mask the input data with the following command:
stack_Mask Test_alt2

- Cluster the data with the following command:
stack_Cluster Test_alt2

- Assemble the data with the following command:
stack_Assemble Test_alt2

- Analyze data with the following command:
stack_Analysis Test_alt2

- Link data with the following command:
stack_Link Test_alt2

NOTE: When using stackPACK from the command line, the user can view
the command line usage of a program by typing the program name
without any operations or parameters specified,
e.g. stack_ProjectManager.

Verify that all programs executed properly by inspecting the output
produced by each of the pipeline steps. The output contains details
such as parameter settings and any errors that may have occurred.

3. If stackPACK fails to process the data, either via the web
interface or command line, please confirm that:
- You have installed all the required third-party dependencies.
- You are using the correct versions of the third-party
dependencies.
- The third-party dependencies have the correct permissions.
- All path locations in the /etc/stackpack configuration file are
valid.
- All the programs in <stackpack install dir>/bin and <stackpack
install dir>/lib are executable for all users.
- All users have write access to the temp directory specified in
STACKPACK_TMP under the [STACKPACK] heading in the /etc/stackpack
configuration file.
- There is enough diskspace.

4. If stackPACK still fails to process the data, please read
through section IX, Troubleshooting.

5. If you are unable to troubleshoot with these suggestions,
please contact Electric Genetics at:
e-mail: support@egenetics.com
tel: +27 (21) 959 3964
fax: +27 (21) 959 2512

6. If you have managed to test successfully, you may delete the
contents of the temporary directory that was created in step
1 of section V, Unpacking The Distribution.

IX. CUSTOMISING YOUR stackPACK CONFIGURATION

1. The stackPACK software has a system-wide configuration file located in
/etc/stackpack from where most of the stackPACK configuration is
done. This configuration file first lists the locations of the
stackPACK system components, then the parameters of the stackPACK
pipeline steps, and lastly the algorithm parameters. The system
administrator should take a critical look at these variables when
first installing stackPACK.

2. The stackPACK configuration file, stackpack, has to be installed in
the default /etc location, but you may place it in any other
location once the setup.sh has completed. To do this set the
STACKPACK_ROOT environment variable for both the webserver, to
enable the web interface tools, and for each user, to enable the
command line tools. To set STACKPACK_ROOT, specify the directory
above the location of the stackpack configuration file. For
example, if the stackpack configuration file is installed in
/usr/local/stackpack/etc, set STACKPACK_ROOT to /usr/local/stackpack.

- To set STACKPACK_ROOT for the webserver edit the Apache
httpd.conf file to contain the following:
SetEnv STACKPACK_ROOT /usr/local/stackpack
Apache needs to be restarted for the newly set variable to take
effect.

- To set STACKPACK_ROOT for each user:
Bash shell: export STACKPACK_ROOT=/usr/local/stackpack
C shell: setenv STACKPACK_ROOT /usr/local/stackpack
Set this in your .bashrc or .cshrc files so that you don't have
to set it in every session.

For the remainder of this document the stackpack configuration file
target will be referred to as the <stackpack config dir>.

NOTE: The odbc.ini and odbsinsts.ini configuration files must be
installed in /etc and may not be moved from this location.

3. Configuring the temp directory:
StackPACK writes out temporary files to the location specified
for STACKPACK_TMP under the [STACKPACK] heading in the stackpack
configuration file. It is important to ensure that enough disk
space is allocated to this directory, especially if there are a
lot of users or if large datasets are processed. The temp directory
can be set in <stackpack config dir>/stackpack.

STACKPACK_TMP=<full path>/tmp

4. Changing the database settings:
To change the username and password used by stackPACK to connect to
the database go to the [DATABASE] heading in
lt;stackpack config dir>/stackpack and edit the DSN_LOGIN and
DSN_PASSWORD variables.

[DATABASE]
ODBCSYSINI=/etc
DSN_NAME=stackPACK
DSN_LOGIN=stackpack <-- --------
DSN_PASSWORD=stackpack <-- --------

5. Changing the SMTP server:
To change the server used to send the e-mail, for example if
stackPACK is not delivering a notification e-mail upon project
submission and completion, change the MAILSERVER value under the
[WEB] heading in <stackpack config dir>/stackpack to point to the
correct machine.

MAILSERVER=smtp.server.com

6. Configuring stackPACK for multi-processor machines:
In <stackpack config dir>/stackpack, under the [stack_Mask],
[stack_Cluster] and [stack_Assemble] headings there is a variable
'num_cpus'. Set this variable to the desired amount of processors
you want to allocate to each task.

Although the number of CPUs set can exceed the number of actual CPUs
on the system, it is not generally recommended. Furthermore, we
recommend that the nature of typical projects, and the available RAM
are taken into consideration when setting this variable. Projects
with long sequences and/or large clusters will require more RAM,
and the system may run out of memory if too many CPUs are set.

[stack_Mask]
............
num_cpus=8
batch_size=250

[stack_Cluster]
num_cpus=8

[stack_Assemble]
num_cpus=8

7. Configuring stackPACK for the old (1996) version of phrap:
In <stackpack config dir>/stackpack, under the [phrap] heading,
there is a variable called old_ace. Set this variable to 0 to use
the older version of phrap.

old_ace=0

8. Changing the machine used as a database server:
To change the machine used as a database server, edit the Server
variable in /etc/odbc.ini

[stackPACK]
...
Server = host.domain

9. User customizable configuration:
StackPACK system configuration can be adjusted by the user with the
creation of an individual configuration file placed in their home
directory named '.stackpackrc'. The easiest way to create the
.stackpackrc file is to copy <stackpack config dir>/stackpack to the
user's home directory as .stackpackrc and further edit it. Each user
can do this as follows:

- cp <stackpack config dir>/stackpack ~/.stackpackrc
- Remove the system configuration section at the top of the
.stackpackrc file with: vi .stackpackrc
- Edit the parameters and locations of the stackPACK programs
with: vi .stackpackrc

The .stackpackrc file settings will override the
<stackpack config dir>/stackpack file settings. User configuration
is also possible with a configuration flag option for each of the
stackPACK programs enabling use of multiple customized configuration
files in any location for different steps in the pipeline and/or for
different projects, for example:

stack_Assemble Altdata --conf=<config file>

NOTE: User configuration is only possible when processing from the
command line.

Typical parameters that are adjusted include: the repeat masking
file, the number of processors for the masking, clustering and
assembly steps and, for expert users, parameters for each of the
programs called externally by stackPACK. Although the most commonly
used parameters for each of these programs are listed in the
configuration file, any parameter can be set as a flag.

X. TROUBLESHOOTING

1. Symptom:
Anomalous behavior is experienced in WebPipe, e.g. extraneous text
is appended to WebPipe upon data submission.

Diagnosis:
This occurs when Netscape FastTrack is used as the web server.

Solution:
The integrity of the data and the stackPACK results are not
affected.Avoid this by using Apache as the web server.

2. Symptom:
The hierarchical navigational icons that represent the various
cluster consensus and alignment views within WebProbe are misaligned.

Diagnosis:
This is due to incompatible font settings when running Netscape
under Linux.

Solution:
Avoid this by setting the Netscape variable width font to 14 in
Edit: Preferences: Font.

3. Symptom:
I get the following error in the command line steps and in WebPipe:

Error: StackDatabase::checkConnection() Failed to connect to
datasource: [unixODBC][TCX][MyODBC]Too many connections

too large: StackDatabase::checkConnection() Failed to connect
to datasource: [unixODBC][TCX][MyODBC]Too many connections.ODBC
Misconfiguration: 9exception

Diagnosis:
The number of client connections to the MySQL server exceeds the
limit.

Solution:
Increase the limit by editing the [mysqld] section in the my.cnf
file, usually in /etc, as follows:

set-variable = max_connections=<number of connections>

Please refer to http://www.mysql.com/doc/T/o/Too_many_connections.html
for further details.

4. Symptom:
One of the following two errors are observed:

- Packet too large

- Error:
Fatal error communicating with database.
StackDatabase::insertObjectAnnotation2() SQLParamData failure:
[unixODBC][TCX][MyODBC]MySQL server has gone away
Please check that:
The database server is working.
Database connectivity is configured correctly.
AssembleApp::execute() - Failed to import

Diagnosis:
When a MySQL client or the mysqld server gets a packet that exceeds
the limit it issues an error and closes the connection.

Solution:
Increase the maximum packet size by editing the [mysqld] and
[mysqldump] sections of the my.cnf file, usually in /etc as follows:

set-variable = max_allowed_packet=16M

Please refer to http://www.mysql.com/doc/P/a/Packet_too_large.html
for further details.

NOTE: MySQL versions lower than 4.0 have a 16 MB packet size
limitation and the maximum connections used during stackPACK
processing may exceed this limit.

5. Symptom:
I get the following error in the web interface:

Traceback (most recent call last):
File "stack_ReportAllMasked.py", line 3, in ?
from corba_connect import *
File "./corba_connect.py", line 2, in ?
from stackCORBA import *
File "./stackCORBA.py", line 13, in ?
import iluRt ; _imported_modules['iluRt'] = iluRt;
_imported_modules['ilu'] = iluRt;
File "./iluRt.py", line 27, in ?
from iluPr import *
ImportError: ld.so.1: python: fatal: relocation error: file
./iluPrmodule.so: symbol PyThread_get_thread_ident: referenced
symbol not found

Diagnosis:
Python has not been compiled with thread support.

Solution:
Compile Python with thread support.

6. Symptom:
I get the following error:

[unixODBC][TCX][MyODBC]Can't connect to local MySQL server through
socket '/tmp/mysql.sock'

Failed to import modules, reason: /usr/local/stackpack/lib/_omnipymodule.so:
undefined symbol: PyUnicodeUCS2_FromUnicode

There will also be the following error message in the httpd
error_log file:

Traceback (most recent call last):
File "/var/www/cgi-bin/stackpack/project.py", line 435, in ?
except CORBA.TRANSIENT, ErrorMessage:
NameError: name 'CORBA' is not defined

Diagnosis:
This is due to an error within ODBC where ODBC does not find the
mysqld.sock file regardless of the location specified under Server
in the /etc/odbc.ini file. It only occurs when the MySQL server
hostname of the MySQL account with user creation privileges was
referred to as 'localhost', rather than '<host>.domain', during
stackPACK installation. MySQL then tries to connect via a UNIX
socket instead of via a TCPIP socket.

The MySQL server hostname is reflected in the /etc/odbc.ini file,
for example:
[stackPACK]
Description = Stack system table
Driver = myodbc
Trace = no
Tracefile =
Server = localhost
Port = 3306
Socket =
Database = stackPACK

Solution:
One of two solutions is possible, although we recommend that you
perform solution 1.
1. Create a symbolic link in the /etc/init.d/mysql file as follows:

ln -s /var/run/mysql/mysqld.sock /tmp/mysql.sock

2. The /etc/odbc.ini file can be edited to reflect the full host and
domain name, as follows:
[stackPACK]
Description = Stack system table
Driver = myodbc
Trace = no
Tracefile =
Server = <host>.domain
Port = 3306
Socket =
Database = stackPACK

NOTE: You will need root permission to edit the /etc/odbc.ini
file. You may also solve this problem with the creation of a
.odbc.ini file in your home directory which then needs to be
edited.

Please refer to the FAQs at the following URL for further
information: http://www.egenetics.com/support.html

XI. CONVERTING stackPACK v2.1.1 PROJECTS TO stackPACK V2.2.1
FORMAT

StackPACK v2.1.1 created projects should be converted to
stackPACK v2.2.1 format if you wish to have access to these
projects on stackPACK v2.2.1. You may carry out further data
processing, output and analysis on these converted projects.

StackPACK must have access to the existing stackPACK v2.1.1
database projects and to the new stackPACK v2.2 database to
do the conversion. The database is called 'stacksys' in
stackPACK v2.1.1 and 'stackPACK' in stackPACK v2.2.1 and is
specified in your /etc/odbc.ini file. Use your stackPACK v2.1.1
<stackpack config dir>/odbc.ini file that was moved to a
temporary location in step 2 of section IV, Uninstalling
existing stackPACK copies, to edit your new stackPACK v2.2.1
/etc/odbc.ini file as follows:

vi /etc/odbc.ini

Your stackPACK v2.2.1 /etc/odbc.ini file should look as follows,
e.g.:

[stackPACK]
Description = Stack system table
Driver = myodbc
Trace = no
Tracefile =
Server = localhost
Port = ####
Socket =
Database = stackPACK

[stacksys]
Description = Stack system table
Driver = myodbc
Trace = no
Tracefile =
Server = localhost
Port = ####
Socket =
Database = stacksys

Projects are converted from stack_ProjectManager - please refer
to the command line user manual for further details.

Please do not hesitate to contact Electric Genetics if you have any
further queries:
e-mail support@egenetics.com
phone +27 (21) 959 3964
fax +27 (21) 9592512