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
- Configuring BioCatalogue
- Running 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.
- imagemagick (for handling service provider logos)
- RVM - get it from https://rvm.io/rvm/install/ and do a multi-user installation.
- Add your user to group
- Run '
rvm requirements' and install packages where needed.
- Add your user to group
Ruby (1.9.2 and above):
Rubygems (we tested versions 1.8 and 2, so no problems expected whichever version you go for):
|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
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.
Download the BioCatalogue code to
The above will create folder
From inside the
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.
Taverna's wsdl-generic parser is using the code developed by Dmitry Repchevsky for Taverna - the source is available under the branch at https://github.com/taverna/taverna-wsdl-generic/tree/wsdl-generic-3.0-service-catalographer. 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.
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:
- Download the source code to e.g. to
- Check the
- Configure your Apache to run WSDLUtils service as explained in Apache configuration file example above.
- Set WSDLUTILS_BASE_URI in
biocat_local.rbto point to the URL of the WSDLUtils service, e.g. 'https://www.biocatalogue.org/WSDLUtils/WSDLUtils.php'.
Copy and edit the following config files (from inside
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 |
Configure your database connection.
- If you want to use the search capabilities, enable it by setting
ENABLE_SEARCH = true
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.
Copy and edit the service categories to suit your domain:
Required files and directories
Create some required files and directories:
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
config/initializers/biocat_local.rb. Then run the following code and re-enable the search afterwards:
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.
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 (
This will start the application in development mode on port 3000 using the Rails' built-in Web server. You can access the application at
From inside the application directory (
CTRL+C to stop the running application.
The logs files are located in
The BioCatalogue application log is in
The Sunspot Solr search server's log is in
The background workers's log is in
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