Administration:Installing WormBase
Contents
- 1 Overview
- 2 Recommendations
- 3 Basic System Configuration
- 4 Install the Webapp
- 5 Checking out the Administration module
- 6 Generic Genome Browser
- 7 Required 3rd-party Applications
- 8 Optional 3rd-party Applications
- 9 Cronjobs
- 10 Testing The Site
- 11 FORMER VERSION OF THIS DOCUMENT
- 12 Appendices
- 13 AUTHOR
Overview
This document describes how to install WormBase locally on your own machine.
Recommendations
Hardware
As of Dec 2010, the suggested minimum hardware requirements for a basic installation of WormBase are:
- 500 GB disk space or greater
- 4 GB RAM or greater
Operating Systems
- Debian Linux "Lenny", 5.07
- Ubuntu 10.10
- Mac OS 10.6
This document only describes installation on Debian. Your actual mileage may vary on other operating systems.
Basic System Configuration
Users And Groups
WormBase uses several user accounts for directory and server permissions. You will need to create these users and several preliminary directories. This process varies significantly from one unix variant to another.
These users should not have a login password. They are to establish privileges only.
acedb group
This is the group that will have write privileges to the acedb directory tree. Acedb administrators should be added to this group.
$ /usr/sbin/groupadd acedb
acedb user
This is the user that the acedb server will run as. It should be a member of the acedb group.
$ /usr/sbin/useradd -g acedb -d /usr/local/wormbase/acedb acedb
This useradd command also adds the new acedb user to the acedb group. Note that the acedb user's home directory was set to /usr/local/acedb, a directory which will be created in the next step.
wormbase group
This is a group that will have write privileges to the wormbase directory tree. WormBase administrators and authors should be added to this group.
$ /usr/sbin/groupadd wormbase
This would be a good time to add yourself to the acedb and wormbase groups.
$ /usr/sbin/usermod -a -G acedb,wormbase [your_login_name]
You may need to re-login for these changes to take effect. Use the groups command to check which groups you are a member of:
% groups
Create Directories
Create a root directory for all WormBase-related files. Although this directory can reside anywhere on your filesystem, for consistency with WormBase proper, we recommend installing at /usr/local/wormbase. You'll need suitable privileges to install in this location.'
The root container for all things WormBase
- /usr/local/wormbase, owner=root group=wormbase mode=drwxrwsr-x
$ cd /usr/local $ sudo mkdir wormbase $ sudo chown root:wormbase wormbase $ sudo chmod 2775 wormbase
The AceDB directory contains acedb and associated databases:
- /usr/local/wormbase/acedb, owner=acedb group=acedb,mode=drwxrwsr-x
$ mkdir /usr/local/wormbase/acedb $ chmod 2775 usr/local/wormbase/acedb $ sudo chown acedb:acedb /usr/local/wormbase/acedb
The website/ directory contains one or many versions of the website:
- /usr/local/wormbase/website, owner=[ANYONE] group=wormbase,mode=drwxrwsr-x
$ mkdir /usr/local/wormbase/website $ chmod 2775 usr/local/wormbase/website $ sudo chgrp wormbase /usr/local/wormbase/website
The services/ directory contains optional services such as e-pcr, blast, and nginx:
- /usr/local/wormbase/services, owner=[ANYONE] group=wormbase,mode=drwxrwsr-x
$ mkdir /usr/local/wormbase/services $ chmod 2775 usr/local/wormbase/services $ sudo chgrp wormbase /usr/local/wormbase/services
The databases/ directory contains support text-file database driving a number of features:
- /usr/local/wormbase/databases, owner=[ANYONE] group=wormbase,mode=drwxrwsr-x
$ mkdir /usr/local/wormbase/databases $ chmod 2775 usr/local/wormbase/databases $ sudo chgrp wormbase /usr/local/wormbase/databases
The logs/ directory contains WormBase-wide log and pid files
- /usr/local/wormbase/databases, owner=[ANYONE] group=wormbase,mode=drwxrwwrwx
$ mkdir /usr/local/wormbase/logs $ chmod 2775 usr/local/wormbase/logs $ sudo chgrp wormbase /usr/local/wormbase/logs
Installing Library Prerequisites
Assuming a vanilla Debian installation, install the following libaries and all of their dependencies via sudo apt-get install. Some of these libraries are discussed below.
gcc
curl
wget
bzip2
mysql-client
mysql-server
mysql-server-5.0
libmysqlclient16-dev
libgd2-xpm-dev
libgd2-xpm
xinetd
libdbd-mysql
libdbd-mysql-perl
libapache2-mod-perl2
libgtk2.0-0
libgtk2.0-dev
libglib
libglib-dev
emacs
mercurial
byacc
libreadline5-dev
flex
libdb4.6
libdb-dev
xml2
libxml2
libxml2-dev
libmysql++-dev
libreadline6-dev
libncurses5/testing
libncurses5-dev/testing
ncurses-bin
libxmu-dev
graphviz
Install Perl 5.10.1 or greater
You'll need Perl version 5.10.1 or greater.
Installing Perl from source
We recommend installing a local version of Perl and required libraries. This makes management dramatically easier. We keep our Perl with the webapp itself.
If you have sufficient privileges, you may wish to use your pre-installed system Perl.
bash> mkdir ~/website/perl bash> cd ~/src bash> curl -O http://www.cpan.org/src/perl-5.10.1.tar.gz bash> cd ~/build bash> tar xzf ../src.perl-5.10.1.tar.gz bash> cd perl-5.10.1 bash> ./Configure -des -Dprefix=$HOME/website/perl/5.10.1 bash> make bash> make test bash> make install
Be sure to set up your your system to preferentially use this newly installed Perl:
bash> export PATH=~/wormbase/perl/5.10.1/bin:${PATH}
Upgrading Perl via apt
Configure your apt preferences
Add the following to /etc/apt/sources.list
#Stable deb http://ftp.us.debian.org/debian stable main non-free contrib #Testing deb http://ftp.us.debian.org/debian testing main non-free contrib #Unstable deb http://ftp.us.debian.org/debian unstable main non-free contrib
Configure your preferences in /etc/apt/preferences:
Package: * Pin: release a=stable Pin-Priority: 700 Package: * Pin: release a=testing Pin-Priority: 650 Package: * Pin: release a=unstable Pin-Priority: 600
Finally, install Perl
sudo apt-get update sudo apt-get install perl/testing perl-base/testing perl-modules/testing libperl5.10/testing libperl-dev/testing
And confirm
$ perl -v This is perl, v5.10.1 (*) built for x86_64-linux-gnu-thread-multi (with 40 registered patches, see perl -V for more detail)
Install the Webapp
See the WormBase source code repository documentation for additional details on using Mercurial. You may need to install mercurial first.
Fetch the current production code from the mercurial repository.
$ cd /usr/local/wormbase/website $ hg clone ssh://hg@bitbucket.org/tharris/wormbase $ hg mv wormbase production // name can be anything you want; useful for maintaining multiple versions
Install local:: lib
The preferred method uses the web app's Makefile.PL and Module::Install to build all dependencies. We maintain local copies of all libraries with each version of the webapp.
local::lib makes installling libraries in a local path a snap.
# Install local::lib. You may need to be root depending on your Perl config. bash> perl -MCPAN -e 'CPAN::install(local::lib)' bash> cd ~/projects; mkdir extlib # a local directory for libraries bash> perl -Mlocal::lib=./ bash> eval $(perl -Mlocal::lib=./)
Configure the environment file for "production"
This file helps you set up your environment for working with different versions of WormBase.
$ cp wormbase.env.template wormbase.env $ perl -p -i -e 's/\[% app %\]/production/g' wormbase.env $ source wormbase.env
Build and install dependencies
$ cd /usr/local/wormbase/website/production $ mkdir extlib $ cd extlib $ perl -Mlocal::lib=./ $ eval $(perl -Mlocal::lib=./) $ cd ../ $ perl Makefile.PL $ make installdeps
Alternatively, install Perl modules manually
Follow the documentation at Managing Perl Libraries for details on how to build and install required Perl modules.
Checking out the Administration module
Fetch the administration code repository (privileged users only, for now)
todd> mkdir -p ~/projects/wormbase todd> cd ~/projects/wormbase todd> hg clone ssh://hg@bitbucket.org/tharris/wormbase-admin/ // Assuming you have already set up your ssh keys at bitbucket
Generic Genome Browser
See Managing GBrowse for details on how to build and install GBrowse.
Required 3rd-party Applications
starman: the lightweight http server
AceDB
I always build acedb from source.
$ tar xzf ACEDB-source* // CAUTION: Tarbomb. // Requires installation of a whole bunch of things first: libgtk2.0-0 libgtk2.0-dev libglib, byacc, etc, etc // Modify the makefile: create a target for server programs (xace tace saceserver sgifacerver) // This is all I care about: SERVERS = xace tace saceserver sgifaceserver saceclient servers: $(SERVERS) $ export ACEDB_MACHINE=LINUX_4 $ make servers $ cd ~acedb $ ln -s bin-VERSION bin $ cp tace xace sgifaceserver saceserver saceclient ~acedb/bin/. $ sudo chown root:root ~acedb/bin/*
Testing the ACeDB Installation
At this point, you can test whether the socket server runs correctly. Provided that you have added yourself to the acedb group, you can run the following command:
% ~acedb/bin/sgifaceserver ~acedb/wormbase // Database directory: /usr/local/wormbase/acedb/wormbase // Shared files: /usr/local/acedb // #### Server started at 2001-07-23_16:42:31 // #### host=mondseer.cshl.org listening port=23100 // #### Database dir=/usr/local/acedb/elegans // #### Working dir=/usr/local/acedb/elegans // #### clientTimeout=600 serverTimeout=600 maxKbytes=0 autoSaveInterval=600 // Server listening socket 28 created
The line "listening port=23100" indicates that the server is listening to port 23100. Open a new terminal window and use saceclient to confirm that you can communicate with the server:
% ~acedb/bin/saceclient localhost -port 23100 Please enter userid: anonymous Please enter passwd: acedb@localhost> find Sequence // Response: 65 bytes.
// Found 236493 objects in this class // 236493 Active Objects acedb@localhost> quit // Closing connection to server. // Client sent termination signal by server. // Response: 13 bytes. // A bientot // Please report problems to acedb@sanger.ac.uk // Bye
Configuring Acedb to start automatically under xinetd
Install xinetd (not standard in Debian) if you didn't already:
$ sudo apt-get install xinetd
Create a configuration file for acedb:
$ sudo emacs /etc/xinetd.d/acedb-wormbase
# file: /etc/xinetd.d/acedb-wormbase
# default: on
# description: wormbase acedb database
service acedb
{
protocol = tcp
socket_type = stream
port = 2005
flags = REUSE
wait = yes
user = acedb
group = acedb
log_on_success += USERID DURATION
log_on_failure += USERID HOST
server = /usr/local/wormbase/acedb/bin/sgifaceserver
server_args = /usr/local/wormbase/acedb/wormbase 1200:1200:0
}
Edit /etc/services. Although xinetd is not supposed to use /etc/services, the following line must be added:
acedb-wormbase 2005/tcp
Restart xinetd with the following command:
$ sudo /etc/init.d/xinetd reload (or restart)
You should now be able to talk to the database using saceclient:
$ ~acedb/bin/saceclient localhost -port 2005
MySQL (required)
Installation
Install mysql and various libraries via apt-get if you haven't already. You will need the unstable and testing repositories set up when upgrading Perl.
$ sudo apt-get install libncurses5/testing
$ sudo apt-get install mysql-common/testing libmysqlclient16 mysql-server-5.1/testing \
mysql-client-5.1/testing libdbd-mysql/testing libdbd-mysql-perl/testing
With this installation, databases are located at /var/lib/mysql. We want to relocate this to /usr/local/mysql/data to be consistent with the WormBase. We also want to able to write to this directory from the command line, so:
$ sudo nano /etc/my.cnf Set datadir to /usr/local/mysql/data $ mkdir -p /usr/local/mysql/data $ sudo chown -R mysql:mysql /usr/local/mysql $ sudo chmod 2775 /usr/local/mysql/data
Mysqld will automatically be setup to launch at server boot (rc3 and rc5).
Set up mysql permissions
$ mysql -u root -pPASSWORD mysql> grant select on c_elegans.* to nobody@localhost;
Repeat for:
- autocomplete
- b_malayi
- c_briggsae
- c_elegans
- c_elegans_gmap
- c_elegans_pmap
- c_japonica
- c_remanei
- c_brenneri
- h_bacteriophora
- p_pacificus
- ps1010
Optional 3rd-party Applications
nginx
We use nginx as an (optional) lightweight proxy server. You can skip this step if desired.
By default, we set nginx to listen on port 80 and forward requests to starman listening on port 5000.
Configuration
BLAST
The BLAST page requires WU-BLAST. This is a closed-source derivative of NCBI's BLAST. However, WU-BLAST is free to academic users (with licensing) and is thought to have performance advantages over NCBI-BLAST; it can be downloaded from http://blast.wustl.edu/. A typical choice of WU-BLAST for Linux is blast2.linux26-i686.tar.gz.
You can skip this step if you don't want to provide BLAST services at your site.
By default, WormBase expects WU-BLAST to be installed in /usr/local/wormbase/services/wublast. This is the directory structure used by WormBase:
$ ls -l /usr/local/wormbase/services/wublast
lrwxrwxrwx 1 root root 18 May 7 12:26 BLOSUM62 -> matrix/aa/BLOSUM62 -rw-r--r-- 1 root root 46789 Feb 5 1998 HISTORY -rw-r--r-- 1 root root 6648 Mar 4 1997 README drwxr-xr-x 2 root root 4096 May 7 12:46 bin/ lrwxrwxrwx 1 root root 25 Jul 24 08:20 databases -> /usr/local/wormbase/blast/ drwxr-xr-x 2 root root 4096 Jan 27 2000 filter/ drwxr-xr-x 4 root root 4096 Oct 4 1998 matrix/
e-PCR
A modified version of the epcr source can be found in the checked out website code in src/. See the enclosed README describing changes made to the original e-PCR distribution. The binary should be placed in /usr/local/wormbase/services.
$ cd /usr/local/wormbase/website/production/src $ make $ install e-PCR /usr/local/wormbase/services/epcr
BLAT
Jim Kent's BLAT (blast-like alignment tool) is a fast nucleotide aligner used by the blast search page. If you do not plan to support blast searches, you may safely skip this step.
$ mkdir -p /usr/local/wormbase/services/blat/bin $ cd /usr/local/wormbase/services/blat/bin $ wget http://www.soe.ucsc.edu/~kent/exe/linux/blatSuite.33.zip (for Intel Linux) $ unzip blatSuite.33.zip $ rm blatSuite.33.zip version.doc 11.ooc
Note that this choice gives precompiled binaries for an Intel-based Linux distribution as of March 2006. It would probably be worth checking http://www.soe.ucsc.edu/~kent/exe/linux to see if there is a more up-to-date version than 33. Also, other operating systems will need other binaries. E.g., for Mac OS X, instead run:
$ wget http://www.soe.ucsc.edu/~kent/exe/osX/blatSuite.33.zip
The blat server will be started automatically by the update script. For reference, the blat server is launched using the following command.
$ /usr/local/wormbase/services/blat/bin/gfServer start localhost 2003 \
/usr/local/wormbase/databases/VERSION/blat/*.nib & > /dev/null 2>&1
Cronjobs
Set up the following cronjobs:
Log Rotation (root cron)
# Rotate WormBase logs 10 1 * * * /home/todd/projects/wormbase/admin/maintenance/rotate_httpd_logs.pl
For nodes running acedb, add the following entry which deals with its massive log files:
# Purge epic ACEDB logs 35 * * * * /home/todd/projects/wormbase/admin/maintenance/purge_acedb_logs.sh
The final step is to arrange for Acedb to start automatically and for MySQL to restart if necessary.
Installing MySQL and BLAT monitoring scripts NOT DONE
Run:
$ cp -i /usr/local/wormbase/util/admin/blat_server.initd /etc/rc.d/init.d/blat_server
Then run:
$ crontab -u root -e
to add the following entries to root's crontab:
0 * * * * /usr/local/wormbase/util/admin/restart_mysqld.pl 0 * * * * /usr/local/wormbase/util/admin/restart_blat.pl
Installing scripts to verify that the servers are running
Two scripts in the WormBase directory can be used to ensure that the mysql and blat servers are running. To install, them:
% sudo cp /usr/localwormbase/util/admin/blat_server.initd \
/etc/rc.d/init.d/blat_server
Place the restart scripts under cron control of a privileged user. These commands will check every hour to see that the servers are running.
% sudo crontab -u root -e
0 * * * * /usr/local/wormbase/util/admin/restart_mysqld.pl 0 * * * * /usr/local/wormbase/util/admin/restart_blat.pl
At the same time, you might also wish to automate the rotatation of logs to prevent them from growing to an unwieldy size. You'll find an appropriate log rotation configuration stanza in util/rotate_wormbase_logs and a log rotate script in /usr/local/wormbase/bin/rotatelogs.pl. You will need both.
# Rotate httpd logs 10 1 * * * /usr/local/wormbase/bin/rotatelogs.pl # Rotate acedb logs 10 1 * * * logrotate /usr/local/wormbase/util/rotate_wormbase_logs
This stanza will check that the acedb server logs do not grow larger than 100 MB.
Testing The Site
At this point, all components of a WormBase installation have been installed. You can test your installation by restarting the various server components of WormBase.
Restarting AceDB
# Via xinetd: $ /etc/init.d/xinetd reload (or restart)
# ...or using saceclient % saceclient localhost -port 2005 acedb> password: acedb> shutdown now
Restarting MySQL
# Via mysqladmin... % mysqladmin -uroot -pPASSWORD shutdown # or using init.d $ /etc/init.d/mysql restart
Restarting Apache
When the configuration files have been checked and adjusted, restart Apache with the following command:
$ /etc/init.d/apache restart
Check /usr/local/wormbase/logs/classic-error_log for WormBase-specific errors and /var/log/apache2/error_log for general errors.
BLAT
% /usr/local/blat/bin/gfServer start localhost 2003 \
/usr/local/wormbase/blat/*.nib & > /dev/null 2>&1
Blocking robots
It can be useful to block search engines (such as Google) from crawling over one's mirror. To do this, go to /usr/local/wormbase/html, and make a file called "robots.txt" with the following contents:
User-agent: * Disallow: /
FORMER VERSION OF THIS DOCUMENT
A much earlier, and now obsolete, version of these site-installation instructions can be seen here.
Appendices
Appendix 1: Mac OS 10.6 (Snow Leopard) Prequisites
XCode > 3.21
You will need this for building C libraries as well as fixing the broken Perl that shipping with 10.6.
MySQL >= 5.1
MySQL is not expressly required, but you do need it for building DBD::mysql.
bash> cd src bash> curl -O http://mysql.mirrors.pair.com/Downloads/MySQL-5.1/mysql-5.1.39.tar.gz bash> tar xzf mysql-5.1.41.tar.gz bash> cd mysql-5.1.41 bash> ./configure --prefix=/usr/local/mysql \ --with-extra-charsets=complex \ --enable-thread-safe-client \ --enable-local-infile \ --enable-shared \ --with-plugins=innobase bash> make bash> sudo make install bash> cd /usr/local/mysql bash> sudo ./bin/mysql_install_db --user=mysql bash> sudo chown -R mysql ./var
libpng
bash> curl -O http://softlayer.dl.sourceforge.net/project/libpng/00-libpng-stable/1.2.40/libpng-1.2.40.tar.gz bash> tar xzf libpng-* bash> ccd libpng* bash> ./configure bash> make bash> sudo make install
libgd
bash> curl -O http://www.libgd.org/releases/gd-2.0.35.tar.gz bash> tar xzf gd* bash> cd gd* bash> ./configure bash> make bash> sudo make install
AUTHOR
Todd Harris (toddwharris@gmail.com)
