0. Prerequisites

Stacks should build on any standard UNIX-like environment (Apple OS X, Linux, 
etc.) Stacks is an independent pipeline and can be run without any additional
external software. To visualize Stacks' data, however, Stacks provides a web-based 
interface which depends on several other pieces of software. 

     Note: Apple OS X does not distribute the OpenMP library (or
     distributes a non-standard version in the case of OS X Server) which
     Stacks relies on for parallel processing. Stacks can still be built
     and run on this system, however, you will have to disable building
     with OpenMP (supply the --disable-openmp flag to configure) and use
     non-parallelized code. If desired, this problem can be fixed in several
     ways including installing an updated version of the GCC compiler, say
     using MacPorts (http://www.macports.org/).

To visualize data, Stacks uses a web-based interface (written in PHP) that interacts 
with a MySQL database server. MySQL provides various functions to store, sort, and 
export data from a database. For this to work, you must have a PHP-enabled Apache web 
server installed as well as the MDB2 Pear module to provide MySQL interaction.

Likewise, several Perl scripts are distributed with Stacks to upload pipeline output
to the MySQL database serer. For these to work, you must have the Perl DBI module 
installed with the MySQL driver.

If you want to export data in Microsoft Excel Spreadsheets, you will need the 
Spreadsheet::WriteExcel Perl module.

Most server installations will provide Apache, MySQL, Perl, and PHP by default. While 
installing these components is beyond these instructions, here are some links that might
be useful:

  1. MySQL Database: http://www.mysql.com/downloads/mysql/
  2. Perl interface to MySQL: http://search.cpan.org/dist/DBD-mysql/
  3. Spreadsheet Perl Module: http://search.cpan.org/~jmcnamara/Spreadsheet-WriteExcel-2.37/
  4. MDB2 Pear Module: http://pear.php.net/package/MDB2/
  5. MDB2 MySQL driver: http://pear.php.net/package/MDB2_Driver_mysql/

(Perl modules are easily installed with the cpan tool, and similarly, PHP modules are
 easily installed with the pear tool. Many operating systems already have these tools
 installed - such as OS X and some Linux distributions. Most Linux systems will provide
 all of these tools as packages that can be installed using yum, apt-get, or a similar
 piece of software.)

Finally, the performance of Stacks can be improved by installing two external libraries.
First, to enable reading of BAM files, install Samtools. Second, to lower memory usage
install Google's SparseHash class. These optional packages must be installed and enabled
prior to building Stacks.

  1. http://samtools.sourceforge.net/.
  2. http://code.google.com/p/sparsehash/

If you are running a version of Linux, all of the above software can be installed via the 
package manager. If you are using Ubuntu, you can install the following packages:

% sudo apt-get install mysql-server php5 apache2
% sudo apt-get install php-mdb2 php-mdb2-driver-mysql
% sudo apt-get install libdbd-mysql-perl
% sudo apt-get install samtools
% sudo apt-get install libbam-dev

A similar set of commands using yum, or another package manager on other Linux 
distributions.

1. Build the software. Stacks uses the standard autotools install:

% tar xfvz stacks_x.xx.tar.gz
% cd stacks_x.xx
% ./configure
% make
(become root)
# make install

You can change the root of the install location (/usr/local/ on most
operating systems) by specifying the --prefix command line option to
the configure script.

% ./configure --prefix=/home/smith/local

You can enable Sparsehash and BAM by adding the following options:

% ./configure --enable-sparsehash --enable-bam

You may need to specify the BAM library location:

% ./configure --enable-bam \
              --with-bam-include-path=/usr/local/include/bam \
              --with-bam-lib-path=/usr/local/lib

Or, if you installed with Ubuntu packages:

% ./configure --enable-bam \
              --with-bam-include-path=/usr/include/samtools \
              --with-bam-lib-path=/usr/lib

A default install will install files in the following way:

/usr/local/bin - stacks executables and perl scripts

/usr/local/share/stacks - PHP files for the web interface 
                          and SQL files for creating the 
                          MySQL database

2. Edit the MySQL configuration file, installed in
/usr/local/share/stacks/sql/mysql.cnf.dist, to enable access to the
database from the Stacks scripts.

% cd /usr/local/share/stacks/sql/
% cp mysql.cnf.dist mysql.cnf

Edit the file to reflect the proper username, password, and host to
use to access MySQL.

The various scripts that access the database will search for a MySQL
configuration file in your home directory before using the
Stacks-distributed copy. If you already have a personal account set up
and configured (in ~/.my.cnf) you can continue to use these
credentials instead of setting up new, common ones.

If you just installed MySQL and have not added any users, you can do so with these
commands:

% mysql
mysql> GRANT ALL ON *.* TO 'stacks_user'@'localhost' IDENTIFIED BY 'stackspassword';

Edit /usr/local/share/stacks/sql/mysql.cnf to contain the username and password
you specified to MySQL.

(This information was taken from: http://dev.mysql.com/doc/refman/5.1/en/grant.html)

3. Enable the Stacks web interface in the Apache webserver.

Add the following lines to your Apache configuration to make the Stacks PHP
files visible to the web server and to provide a easily readable URL to access
them: 

<Directory "/usr/local/share/stacks/php">
        Order deny,allow
        Deny from all
        Allow from all
</Directory>

Alias /stacks "/usr/local/share/stacks/php"

A sensible way to do this is to create the file stacks.conf in either the

/etc/apache2/conf.d/ or /etc/httpd/conf.d/

directory (depending on your Linux distro). Place the above lines in this file and 
restart the apache server:

# vi /etc/apache2/conf.d/stacks.conf
# apachectl restart

(See the Apache configuration for more information on what these do:
http://httpd.apache.org/docs/2.0/mod/core.html#directory)

Edit the PHP configuration file (constants.php.dist) to allow it access to the 
MySQL database. Change the file to include the proper database
username ($db_user), password ($db_pass), and hostname ($db_host). Rename the 
distribution file so it is active.

% cp /usr/local/share/stacks/php/constants.php.dist /usr/local/share/stacks/php/constants.php
% vi /usr/local/share/stacks/php/constants.php

You may find it advantageous to create a specific MySQL user with limited
permissions - SELECT, UPDATE, and DELETE to allow users to interact
with the database through the web interface.

4. Enable web-based exporting from the MySQL database.

Edit the stacks_export_notify.pl script to specify the email and SMTP
server to use in notification messages.

Ensure that the permissions of the php/export directory allow the
webserver to write to it. Assuming your web server user is 'www':

% chown www /usr/local/share/stacks/php/export