Skip to end of metadata
Go to start of metadata

BioCatalogue is a Ruby on Rails 3 application. This document describes how to set BioCatalogue up in development mode (e.g. if you just want to try it out or do some development on it). It assumes you have superuser privileges.

If you need a production-level service - please see the installation instructions for production.

Table of Contents

Installing BioCatalogue

OS and managed packages

This installation uses Ubuntu 12.04 Server 64bit.

A few main packages that are required:

  • Java (needed to run Solr search server and wsdl-generic WSDL parser for BioCatalogue - see below for details)
    • Make sure you have Java SDK (and not just JRE) installed and $JAVA_HOME environment variable set.
  • git-core
  • mysql-server
  • memcached
  • imagemagick (for handling service provider logos)

Other software


  • RVM - get it from and do a multi-user installation.
    • Add your user to group rvm.
    • Run 'rvm requirements' and install packages where needed.
  • Ruby (1.9.2 and above):

  • Rubygems (we tested versions 1.8 and 2, so no problems expected whichever version you go for):

  • Bundler:

  • Gems

Install the appropriate version of Rails - needs to be greater than 3.2.



If you do not have it already, to install MySQL, e.g. on Ubuntu, run the following command:

  • Create a mySQL user for the BioCatalogue application, e.g. called biocat, and the BioCatalogue database, and grant the access to it to biocat user:

On some more recent versions of mySQL we noticed that you also have to do the following to get the database setup (below) to work.

BioCatalogue software

  • Download the BioCatalogue code to e.g. /var/webapps

  • The above will create folder /var/webapps/biocatalogue.

  • From inside the biocatalogue folder do:

WSDL document parsing software

BioCatalogue is using two external libraries for WSDL document parsing - the main one is based on Taverna's wsdl-generic module written in Java and the other one is the PHP WSDLUtils library and is used as a back up. It is not necessary to set up the back up one but it is a good idea as it can parse some WSDLs that the main one fails to parse.

wsdl-generic parser

Taverna's wsdl-generic parser is using the code developed by Dmitry Repchevsky for Taverna - the source is available under the wsdl-generic-3.0-service-catalographer branch at In BioCatalogue it is being used via rjb/Ruby Java Bridge so you have to make sure that you have Java SDK (and not just JRE) installed and that you have set the JAVA_HOME environment variable to point to your Java SDK folder.

Installing Java SDK on Ubuntu
Setting JAVA_HOME environment variable, e.g. in system-wide /etc/environment
WSDLUtils parser

The back up WSDL document parser WSDLUtils is an external PHP utility software that has to be run under Apache or a similar Web server. If you ever have to use/fallback to WSDLUtils, you should:

  • Install PHP

  • Download the source code to e.g. to /var/www/WSDLUtils:


  • Check the README.txt file.
  • Configure your Apache to run WSDLUtils service as explained in Apache configuration file example above.
  • Set WSDLUTILS_BASE_URI in biocat_local.rb to point to the URL of the WSDLUtils service, e.g. ''.

Configuring BioCatalogue

Configuration files

Copy and edit the following config files (from inside /var/webapps/biocatalogue):



Configure log rotation here.


Configure the address of the memcache server. Memcache server is used for caching stuff from the BioCatalogue application, you do not have to use it though.


Configure the address of the Solr search server.


Make sure you also enable search in config/initializers/biocat_local.rb



Configure your database connection.

  • If you want to use the search capabilities, enable it by setting ENABLE_SEARCH = true
  • etc.

If you want the application to send emails, configure it here.

Need to ensure there is something in the :domain field and that starttls is enabled. See the SES docs for more information.

Also, make sure that ActionMailer::Base.perform_deliveries is set to true.




If you want to change the colours and style used by the BioCatalogue application, this is the place to do it.

Service categories

Copy and edit the service categories to suit your domain:

Required files and directories

Create some required files and directories:

Database setup

Provided you have installed mySQL server and created the BioCatalogue database, you now have to create the necessary tables.

Firstly, temporarily set ENABLE_SEARCH to false in config/initializers/biocat_local.rb. Then run the following code and re-enable the search afterwards:

Running BioCatalogue

The application consists of several services and a number of background jobs:

  • mySQL server
  • memcache server
  • BioCatalogue app itself
  • Sunspot Solr search server (requires Java)
  • Workers for various background processing, e.g. sending emails, etc. If you do not want the application to send emails - you do not have to run the workers.
  • WSDLUtils service for parsing WSDLs

BioCatalogue, Solr and delayed_job workers come together when you checkout the BioCatalogue application from GitHub.

WSDLUtils can be installed as explaned above.

mySQL and memcache either come with the system by default or can be installed using apt-get or similar package manager as explained above.

Starting BioCatalogue

Start the mySQL server. Start the memcache server, if you want.

Once you have finished configuring all the services and the BioCatalogue application as explained above, you can run the BioCatalogue application from inside the application directory (/var/webapps/biocatalogue) with:

This will start the application in development mode on port 3000 using the Rails' built-in Web server. You can access the application at http://localhost:3000.

Stopping BioCatalogue

From inside the application directory (/var/webapps/biocatalogue) do CTRL+C to stop the running application.

Log files

The logs files are located in /var/webapps/biocatalogue/log/.

The BioCatalogue application log is in /var/webapps/biocatalogue/log/development.log

The Sunspot Solr search server's log is in /var/webapps/biocatalogue/log/sunspot-solr-production.log.

The background workers's log is in /var/webapps/biocatalogue/log/delayed_job.log.

Rake tasks for report generation

There are a few Rake tasks that you can run from the BioCatalogue application folder (/var/webapps/biocatalogue). Curation dashboard part of the BioCatalogue application relies on some of the below reports being generated and in place for the application to pick up.

  • Update the stats
  • Links checker report - links that need curator attention
  • Service annotation report



  1. 2014-01-15

    Section Configuring BioCatalogue  Configuration files added extra *.pre files