Installation guide: compiling ZENBU

ZENBU server side web services and command line tools are written in c/c++ and perl. This section of the Installation guide will cover the server side directory structure and compiling of the ZENBU webservices and tools.

System setup

ZENBU is a web application which requires a basic web-stack of apache2, fastcgi, mysql, sqlite3. On debian linux systems the following apt-get commands should install the required systems

apt-get install apache2
apt-get install libapache2-mod-fcgid
apt-get install mysql-server
apt-get install mysql-client
apt-get install sqlite3

In addition ZENBU uses the commandline samtools program for processing BAM/SAM files as part of the the data file upload system. You can either install from a debian package or from source code downloaded from http://samtools.sourceforge.net/

apt-get install samtools

Development library dependancies

C libraries dependencies

In order to compile ZENBU you will need the following c/c++ libraries : libmysql-devel, libsqlite3-devel, libfcgi http://www.fastcgi.com, libcurl, libcurl-devel, libssl, libcrypto, rapidxml http://rapidxml.sourceforge.net/, boost 1.43 or later http://www.boost.org, bamtools https://github.com/pezmaster31/bamtools, lz4 compression library, http://code.google.com/p/lz4/

for debian linux systems the following apt-get commands should install the required libraries.

apt-get install g++
apt-get install make
apt-get install cmake
apt-get install libfcgi-dev
apt-get install libmysqlclient-dev
apt-get install libmysql++-dev
apt-get install libsqlite3-dev
apt-get install expat
apt-get install libexpat1-dev
apt-get install openssl
apt-get install uuid-runtime
apt-get install libssl-dev
apt-get install libcrypto++-dev 

ZENBU uses the boost library version 1.43 or greater. This library is sometimes available with linux distributions. In debian7 for example you can install boost from libboost-dev. If this is not available or there are compatibility issues, we have included a copy of boost 1.43 inside the zenbu/src/c++ directory. Or you can download directly from http://www.boost.org

apt-get install libboost-dev

If you have trouble compiling and get boost errors, please install this complete package.

apt-get install libboost-all-dev

ZENBU uses libcurl for SMTP mail functionality. http://curl.haxx.se/libcurl/c/curl_easy_setopt.html SMTP was added into libcurl 7.20 but many linuxes ship with libcurl 7.19 If your linux has the libcurl4 libraries in their package manager you can install with apt-get. If these packages are not available, please install the most recent version of libcurl from source code from http://curl.haxx.se/download.html

apt-get install libcurl4-openssl-dev

Special libraries installed from source

ZENBU also requires several library packages which are often not prepacked with linux distributions. Please download and install these from source

bamtools

DEPRECATED In earlier versions (2.8 and 2.9), ZENBU required the bamtools library. In version 2.10 and on on, ZENBU uses samtools and htslib. This section remains here for legacy building of 2.8 and 2.9 versions.

Download, compile and install from https://github.com/pezmaster31/bamtools. This can be downloaded via git or as a zip from this page. To download via git

git clone git://github.com/pezmaster31/bamtools.git

Compiling is done by

 cd bamtools-master/
 mkdir build
 cd build
 cmake ..
 make
 make install

After installation, you will most likely need to rebuild your shared-library cache. This is done with ldconfig. By default bamtools installs in /usr/local/lib/bamtools which may not be found by ldconfig. On debian7

 cd /etc/ld.so.conf.d
 vi lib.conf
 #add line /usr/local/lib/bamtools
 #save file
 ldconfig

Other library dependencies

ZENBU uses two other libraries: lz4 and rapidxml. These are generally not included in linux distriubutions but are also difficult to compile. To ease the compiling of ZENBU we have included these with the ZENBU source code and modified them as needed. We have tested compiling on debian6 and debian7. The following is for information only and to give credit to the library developers. There is no need to download again, but we provide the information if you run into difficulty.

lz4 compression library

ZENBU uses the fast compression library lz4 http://code.google.com/p/lz4/. We have include a modified copy in the zenbu source tree so there is no need to install separately.

rapidxml

rapidxml is a fast inline xml parser. http://rapidxml.sourceforge.net/ it is a header only c++ library so it does not need compiling. We have included a copy in the zenbu source tree so there is no need to install it separately.

Perl Libraries

ZENBU use perl for the OpenID login webservices and requires the following libraries. They can be install usually though the standard linux distribution apt-get call, but if there are problems, we also list up the libraries.

apt-get install libdata-uuid-perl
apt-get install libyaml-perl
apt-get install libclass-dbi-mysql-perl  
apt-get install libclass-dbi-sqlite-perl
apt-get install libcgi-application-perl
apt-get install libcgi-fast-perl
apt-get install libnet-openid-common-perl 
apt-get install libnet-openid-consumer-perl 
apt-get install libcrypt-openssl-bignum-perl 
apt-get install libio-all-lwp-perl
apt-get install liblwp-authen-oauth-perl
apt-get install liblwpx-paranoidagent-perl 
apt-get install libnet-ping-external-perl
apt-get install libxml-treepp-perl
apt-get install libcache-perl

Data::UUID
XML::TreePP
Time::HiRes
File::Temp
Cache::File
Getopt::Long
Compress::Zlib
DBI
DBD::mysql
DBD::SQLite
IO::All
IO::All::LWP
IO::Socket::SSL
Math::BigInt
Math::BigRat
Math::BigInt::FastCalc
XML::SAX
XML::Simple
XML::XPath
XML::Parser
CGI
CGI::Session
CGI::Fast
Crypt
Crypt::DH
Crypt::DH::GMP
Crypt::OpenSSL::Bignum
YAML
LWP::UserAgent
LWPx::ParanoidAgent
LWP::Authen::OAuth
LWP::Protocol::https 
Net::Yadis
Net::Ping
Net::SSL
Net::HTTPS 
Net::OpenID::Common
Net::OpenID::Consumer

On RedHat and Centos machines, the GNU multiprecision math library (https://gmplib.org/) is usually not installed. The perl package Crypt::DH::GMP requires this library, so please download from source code and install GMP (https://gmplib.org/#DOWNLOAD)

Compiling ZENBU

ZENBU requires a specific directory structure to support background processing and data uploading. In particular ZENBU requires the server machine to have a /zenbu directory at the root level, but this /zenbu directory can by sym-linked to another volume. In fact since ZENBU can use a lot of disk space from uploaded data, I recommend people to place their zenbu directory on a multi-terrabyte volume and symlink.

mkdir /zenbu /zenbu/src /zenbu/dbs /zenbu/cache /zenbu/bin /zenbu/server_config /zenbu/users /zenbu/www
chown www-data /zenbu/cache
chown www-data /zenbu/users
#the owner must be the apache process owner, on some systems is it httpd, or apache or www-data
#alternate is to do chmod 777 or chgrp to allow the apache process to write into the directories cache and users

Next unpack your ZENBU source code. If you received as a .tar.gz it will be created with absolute paths. If not please install in the /zenbu/src directory with the version number of the ZENBU you have downloaded.

tar -Pxzf ZENBU_2.9.0.tar.gz
#this was made with absolute paths so it should unpack into /zenbu/src/ZENBU_2.9.0

after unpacking the source code, please follow these steps to compile. If all the libraries and dependencies are correct this should compile with out errors but maybe a few warnings depending on the version of linux you are using.

cd /zenbu/src/ZENBU_2.9.0/c++
make

Installing ZENBU web-site, cgi and tools

The ZENBU website is located in the source code in the subdirectory www/zenbu. To make setup easier we recommend using the /zenbu/www directory for different versions of the web-site code and then symbolic link from the apache html directory to the appropriate zenbu version.

cp -rp /zenbu/src/ZENBU_2.9.0/www/zenbu /zenbu/www/zenbu_2.9.0
rm /zenbu/www/zenbu     #optional if upgrading from previous version
ln -s /zenbu/www/zenbu_2.9.0  /zenbu/www/zenbu  #the most recent version

The next step is to install the commandline and background processing tools. These get installed into the /zenbu/bin directory

cd /zenbu/src/ZENBU_2.9.0/c++/tools
make
make install
#will copy the commandline tools into /zenbu/bin

Next compile and copy the ZENBU cgi programs into the zenbu website cgi directory

cd /zenbu/src/ZENBU_2.9.0/c++/cgi
make
cp -f *cgi /zenbu/www/zenbu_2.9.0/cgi/

Finally, depending on where your linux keeps the apache html pages, link the current website version into that directory

cd /var/www
ln -s /zenbu/www/zenbu_2.9.0  zenbu

The next step is configuring your ZENBU website.