The Stacks Pipeline
-------------------

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. 

     Note: Apple OS X does not use the GNU Compiler Collection, which is 
     standard on Linux-based systems. Instead, Apple distributes CLANG, 
     which is a nice compiler but does not yet support the OpenMP library
     which Stacks relies on for parallel processing. Stacks can still be built
     and run on an Apple system, however, you will have to disable building
     with OpenMP (supply the --disable-openmp flag to configure) and use
     non-parallelized code. If you want to install a parallelized version of
     Stacks, you can install GCC by hand, or using a package system such as 
     Homebrew (http://brew.sh/) or MacPorts (http://www.macports.org/).

Several Perl scripts are distributed with Stacks to run the pipeline components and
upload pipeline output to the MySQL database serer. For these to work, you must have
the Perl DBI module installed with the MySQL driver. Most Linux distributions will
include the Perl DBI module, but if not Perl modules are easily installed with the
cpan tool.

1. Install optional components:

The performance of Stacks can be improved by installing two, optional external libraries.
First, to enable reading of BAM files, install Samtools: 

    http://samtools.sourceforge.net/.

    Note: Stacks is not yet compatible with newer Samtools versions that use HTSlib. For
    now, you must use Samtools version 0.1.19, which was the last non-HTSlib version:
       http://sourceforge.net/projects/samtools/files/samtools/0.1.19/

Second, to lower memory usage install Google's SparseHash class.

    http://code.google.com/p/sparsehash/

If you are running a version of Linux, 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 libdbd-mysql-perl
% sudo apt-get install libsparsehash-dev
% sudo apt-get install samtools
% sudo apt-get install libbam-dev

A similar set of commands can be executed on a RedHat derived Linux system using yum,
or another package manager on other Linux distributions.

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

% tar xfvz stacks_x.xx.tar.gz
% cd stacks_x.xx
% ./configure

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

% make

You can speed up the build if you have more than one processor:

% make -j 8

3. Install the software.

% sudo make install

A default Stacks 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

The pipeline is now ready to run. The remaining install instructions are to get the
web interface up and running. The web interface is very useful for visualization and
more or less required for building genetic maps. However, Stacks does not depend on
the web interface to run.


The Stacks Web Interface
------------------------

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.

0. Prerequisites

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. Spreadsheet Perl Module: http://search.cpan.org/~jmcnamara/Spreadsheet-WriteExcel-2.37/
  3. MDB2 Pear Module: http://pear.php.net/package/MDB2/
  4. MDB2 MySQL driver: http://pear.php.net/package/MDB2_Driver_mysql/

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

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

2. 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
	Require all granted
</Directory>

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

A sensible way to do this is to create the file stacks.conf with the above lines.

If you are using Apache 2.3 or earlier:
---------------------------------------
Place the stacks.conf file in either

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

directory (depending on your Linux distro) 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)

If you are using Apache 2.4 or later:
---------------------------------------
Place the stacks.conf file in

/etc/apache2/conf-available

directory and then create a symlink to it in the

/etc/apache2/conf-enabled

directory. Then restart Apache. Like so:

# vi /etc/apache2/conf-available/stacks.conf
# ln -s /etc/apache2/conf-available/stacks.conf /etc/apache2/conf-enabled/stacks.conf
# apachectl restart

3. Provide access to the MySQL database from the web interface

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
