Installing Development Environment¶
- Installation
- - App
- - Bootstrap
- - Database
- - Ferret Server
- - Gem
- - Performance Upgrade
- - Source
- - Testing
- - Web Server
STOP: These instructions are aimed at supporting the open source community so if you do not look like this picture you may want to contact TheEdge for a deployment pack for the enterprise version.
These installation instructions cover setting up BioRails on an Ubuntu operating system and supporting the application with a MySQL database. Included is a description for setting up a web service to support the application in a production environment.
Core Environment¶
sudo apt-get install build-essential mysql-server mysql-client subversion sudo apt-get install ruby libzlib-ruby rdoc eruby irb libsvn-ruby ri libmysql-ruby libdbd-mysql-ruby sudo apt-get install imagemagick libmagick9-dev librmagick-ruby graphviz ruby1.8-dev libmysqlclient15-dev sudo apt-get install openssl htmldoc gnuplot rake zip sudo apt-get install sqlite3 libsqlite3-dev mongrel
Installing Rubygems¶
It is better to use the latest version of ruby gems therefore:
# cd $HOME # wget http://rubyforge.org/frs/download.php/38646/rubygems-1.2.0.tgz # tar xvzf rubygems-1.2.0.tgz && cd rubygems-1.2.0 # sudo ruby setup.rb
Download the latest version of rubygems available (currently 1.2.0).
If Ubuntu complains that the ‘gem’ command is not found, you may have to create a symbolic link like this:- sudo ln /usr/bin/gem1.8 /usr/bin/gem
- sudo gem update ––system
taken from http://beans.seartipy.com/2008/07/22/setting-up-rails-development-environment-on-ubuntu-gnulinux/
Gems¶
The gem install for rails can take some time and often has to be called twice for no apparent reason.
sudo gem install rails sudo gem install mocha sudo gem install ntp sudo gem install tzinfo sudo gem install gnuplot sudo gem install mongrel sudo gem install mongrel_cluster sudo gem install icalendar sudo gem install mime-types sudo gem install builder sudo gem install rmagick or mini_magick sudo gem install hpricot sudo gem install json sudo gem install uuid sudo gem install uuidtools sudo gem install ZenTest sudo gem install rspec sudo gem install crypt sudo gem install roodi sudo gem install htmldoc sudo gem install rcov sudo gem install fastercsv sudo gem install rubyzip sudo gem install sqlite3-ruby sudo gem install ruby-net-ldap sudo gem install archive-tar-minitar sudo gem install chronic
To check use
gem list --local
To update use
sudo gem update
Source Code¶
For a development environment
mkdir trunk svn co http://biorails.org/svn/biorails/core/trunk trunk/
For a stable snapshot with no updates or commits (non available for v3) take a snapshot from http://redmine.biorails.org/projects/list_files/core
wget http://redmine.biorails.org/attachments/download/221?filename=biorails-3.0-2772.tar.gz tar -zvxf biorails-3.0-2772.tar.gz
Database¶
Connections¶
We need to set the connection strings in the database.yml file, assuming you are in the trunk/ or branch/ directory...
cp config/database_template.yml config/database.yml nano config/database.yml
Then set the connections, for example
development: adapter: mysql database: biorails_development username: biorails password: moose host: localhost test: adapter: mysql database: biorails_test username: biorails password: moose host: localhost production: adapter: oracle database: localhost username: biorails_validation password: moose
Schema¶
Create MySQL databases
A script is provided to create the MySQL databases and grant the correct access to users
/* Will need to login to mysql as root to initial run this script eg. * mysql -u root -p */ create user biorails identified by 'moose'; create user 'biorails'@'localhost' identified by 'moose'; create database biorails_development; grant all on biorails_development.* to 'root'@'localhost'; grant all on biorails_development.* to 'biorails'@'localhost'; create database biorails_test; grant all on biorails_test.* to 'root'@'localhost'; grant all on biorails_test.* to 'biorails'@'localhost'; create database biorails_production; grant all on biorails_production.* to 'root'@'localhost'; grant all on biorails_production.* to 'biorails'@'localhost';
The script can be run form the command line thus..
mysql -u root -p < db/create_databases.mysql
Create Schemas
The simplest method is to create an empty schema using a rake task once the environment is set
rake db:schema:load
This canbe repeated for the production database, however, there are a number of rake utilities that can be utilised to populate the production database in a more controlled manner. To review the tasks
rake -T
Testing¶
Quick Check¶
Run a basic check to test the installation
rake biorails:check:all
This will check all the dependencies as well as checking the entries in the database. The output of a freshly bootstrapped database will look something like
alces@JeOSBR:~/trunk$ rake biorails:check:all (in /home/alces/trunk) "" "Running model check" "For [development] database biorails_development as user biorails" "==================================================" model UserRole has 10 columns starts at 3 model ProjectType has 10 columns starts at 1 model ProjectRole has 10 columns starts at 1 model User has 23 columns starts at 1 model Identifier has 12 columns starts at 1 model Permission has 4 columns starts at 1 model RolePermission has 5 columns starts at 4 model UserSetting has 9 columns is empty model SystemSetting has 8 columns starts at 1 model DataContext has 12 columns starts at 1 model DataConcept has 12 columns starts at 1 model DataSystem has 16 columns starts at 1 model ListElement has 16 columns starts at 2 model ModelElement has 16 columns starts at 1 model SqlElement has 16 columns is empty model DataType has 9 columns starts at 1 model DataFormat has 12 columns starts at 1 model ParameterType has 12 columns starts at 1 model ParameterRole has 9 columns starts at 1 model AssayStage has 8 columns starts at 1 model ProjectType has 10 columns starts at 1 model AssayStage has 8 columns starts at 1 model Compound has 13 columns is empty model Batch has 13 columns is empty model Team has 12 columns starts at 1 model Project has 21 columns starts at 1 model Membership has 9 columns starts at 1 model ProjectElement has 23 columns starts at 1 model Asset has 20 columns is empty model Content has 22 columns is empty model DbFile has 2 columns is empty model Assay has 17 columns starts at 1 model AssayParameter has 13 columns starts at 1 model AssayQueue has 15 columns is empty model AssayProcess has 17 columns starts at 1 model AssayWorkflow has 17 columns is empty model ProcessInstance has 15 columns starts at 1 model ProcessFlow has 15 columns is empty model ProcessStep has 13 columns is empty model ProcessStepLink has 4 columns is empty model ParameterContext has 13 columns starts at 1 model Parameter has 24 columns starts at 1 model List has 11 columns is empty model ListItem has 5 columns is empty model Request has 18 columns is empty model RequestService has 17 columns is empty model QueueItem has 23 columns is empty model Report has 14 columns starts at 1 model ReportColumn has 24 columns starts at 1 model Experiment has 19 columns starts at 1 model Task has 22 columns starts at 1 model TaskContext has 10 columns starts at 1 model TaskValue has 12 columns starts at 1 model TaskText has 10 columns is empty model TaskReference has 13 columns starts at 1 Models check passed OK UserSetting, SqlElement, Compound, Batch, Asset, Content, DbFile, AssayQueue, AssayWorkflow, ProcessFlow, ProcessStep, ProcessStepLink, List, ListItem, Request, RequestService, QueueItem, TaskText have no data in them yet
Full Test¶
To run a full test you will need to start the ferret server and run the test (this is best run with the development server running which will require bootstrapping, see below)export RAILS_ENV=test rake biorails:ferret_start rake test
Bootstrapping¶
The application can be bootstrapped using another rake task
rake biorails:db:bootstrap
This will create a minimal database with a user admin/admin
There are many more rake tasks available to checking the schema and obviously rake test to test the installation but if you are anything like me you will want to run the application up ASAP.
ruby script/server
and opening a web browser on http://0.0.0.0:3000
Login with admin/admin
If you can log in then you should see an almost empty BioRails application ... well done.
Setting up a Web Server¶
To run BioRails in production in a multi-user system it makes sense to use an application server. We will use a fast scalable web server ideal for web apps http://www.lighttpd.net/
To install
sudo apt-get install lighttpd
Modify your /etc/lighttpd/lighttpd.conf file to set up your domains. Be careful because, by default, Ubuntu maps all the images so that they are taken from /usr/share/images instead of your/rails/root/public/images so if you're wondering why your rails app is working but your images aren't being displayed this is why. You can take out the offending code in your lighttpd.conf.
Time to enable some modules for lighttpd. There are others that you may need but they should be enabled in your lighttpd.conf. There is a template in the config/ directory
nano config/lighttpd-template.conf
and change the top lines to point to the public directory of the BioRails application
########################################################################
# lighttpd configuration file
#
# use it as a base for lighttpd 1.0.0 and above
#
# $Id: lighttpd.conf,v 1.7 2004/11/03 22:26:05 weigon Exp $
#
############ Options you really have to take care of ####################
server.modules = ("mod_rewrite", "mod_access", "mod_redirect", "mod_proxy", "mod_compress", "mod_accesslog")
server.document-root = "/home/biorails/enterprise/trunk/public/"
server.errorlog = "/var/log/lighttpd/error_log"
server.dir-listing = "disable"
## files to check for if .../ is requested
server.indexfiles = ("index.html", "index.htm", "index.rb")
Copy this file into the correct directorysudo cp config/lighttpd-template.conf /etc/lighttpd/lighttpd.conf
Let's make sure that there are no errors by stopping lighttpd and then starting it manually:
sudo /etc/init.d/lighttpd stop sudo lighttpd -f /etc/lighttpd/lighttpd.conf
If you have errors there make sure you take a look and try to address them! The output you see will be your best bet in getting help from somebody on one of the forums.
Configuring the Ferret Server¶
Acts_as_ferret is a plugin for Ruby on Rails which makes it simple to implement full text search for Rails. It builds on Ferret which is a ruby port of Apache Lucene. It is a technology suitable for nearly any application that requires full-text search. For more information about Ferret, visit its website, search the mailing list at ruby-forum.com or (very recommended) buy the book.
Prerequisites¶
- Recent versions of Ferret ( >= 0.10)
- acts_as_ferret (>= 0.4)
Features¶
- High speed full text search across the contents of any Rails model class, without any hassles. The index will be kept up to date automatically while you work with your Rails model classes as usual.
- Each Model class calling acts_as_ferret gets its own Ferret index on disk, but you can search multiple models at once using the multi_search method.
- Supports Rails' single table inheritance mechanism (just declare acts_as_ferret in the base class, and be able to search across all inheriting classes, see TypoWithFerret for an example)
- Aaf is not limited to indexing the attributes of your model: You can tell it to index the result of any instance method of your model class.
- Further customization of the indexing process can be achieved by overriding the to_doc instance method in your model class, which is supposed to return the Ferret document object to be stored in the index.
- Use my_model_instance#more_like_this to retrieve objects having similar contents like my_model_instance. Great for suggesting related pages to your readers, or related products to your customers.
- DRb Server for centralized index access in production environments. This is required as soon as more than one process needs to update the Ferret index, which is true for most deployments with multiple Mongrel / fastCGI instances.
Configuration¶
Ferret is called as an external process when in production mode. This is set in the RAILS_ROOT/config/environments/production.rb file
FERRET_SERVER_REMOTE = true
In order to connect to the server we need to edit the RAILS_ROOT/config/ferret_server.yml file with the following entries
production: host: ferret.yourdomain.com port: 9010 pid_file: log/ferret.pid
Running The Server¶
When running for the first time it is advised to delete the contents of the RAILS_ROOT/index/production folder
To start the server
RAILS_ENV=production ruby script/runner "load 'script/ferret_start'"
and to stop it
RAILS_ENV=production ruby script/runner "load 'script/ferret_stop'"
To simplify the process we have included these calls in the rake tasks
rake biorails:start rake biorails:stop rake biorails:restart
Testing that it Works¶
So how do you see that it works? The server writes every arriving method call to RAILS_ROOT/log/ferret_server.log, so there you should see all the saves and searches fly by if your app is in use.
Performance Upgrade¶
Run in production to improve the general performance of the application as well as running the asset builder which will create a base file for the style and javascript used in the application.
export RAILS_ENV=production rake asset:packager:build_all
rake biorails:start
