Installation Notes for SLIMarray

SLIMarray has been tested to work on Linux (CentOS 4, Fedora Core 5) and Windows XP. Installation instructions below are generic for all operating systems, with the exception of a few operating system-specific notes at the end of this document. Instructions here are for use with a MySQL database. Ruby on Rails should work with a number of different databases, however with the exception of SQLite, these have not been tested specifically with SLIMarray.

Prerequisite Software

The following external software should be installed, following the instructions provided with each of them for your specific operating system:

• Ruby >= 1.8.4 - www.ruby-lang.org (Linux) or rubyinstaller.rubyforge.org (Windows)
• MySQL Server >= 4.2 - www.mysql.com/
• OPTIONAL: OpenLDAP - www.openldap.org
• OPTIONAL: LightTPD - www.lighttpd.net
• OPTIONAL: Subversion - subversion.tigris.org
• For difficulties installing any of these, please see the abundant

documentation, forums and mailing lists for each of them on the internet.

Install Ruby Extras

If you’re using Linux, you’ll need to make sure you have rdoc, irb and the ruby development package. If you’re using Fedora Core or Centos, you should be able to obtain all of these with ‘yum install ruby ruby-rdoc ruby-irb ruby-devel’. In Windows, all of these are installed by default with the Windows Ruby installer.

(Linux Only) This step isn’t necessary with Windows, since Ruby for Windows comes with RubyGems by default. Here’s how to install RubyGems on Linux:

        wget http://rubyforge.org/frs/download.php/5207/rubygems-0.8.11.tgz
        tar zxf rubygems-0.8.11.tgz
        cd rubygems-0.8.11
        ruby setup.rb

(Optional) Install rake using RubyGems: This is necessary if you want to set up the database structure from scratch, or for any development:

        gem install rake

(Optional, Linux) Install ruby-ldap: This is only necessary if you plan to use LDAP to authenticate users. It requires installing OpenLDAP FROM SOURCE. At present, using OpenLDAP for authentication has only been tried on Linux. Here are the steps once OpenLDAP source is installed:

        wget
        http://superb-west.dl.sourceforge.net/sourceforge/ruby-ldap/ruby-ldap-0.9.5.tar.
        gz
        tar zxf ruby-ldap-0.9.5.tar.gz
        cd ruby-ldap-0.9.5
        ruby extconf.rb
        make
        make install

MySQL Configuration

Option 1 - If you’re using an existing MySQL server and are familiar with it:

Create the following database(s) as well as a user to access them:

• slimarray_production (required): the production instance of your database
• slimarray_development (required): you’ll need this to see if the software

is working

• slimarray_test (optional): you’ll need this for unit and functional testing

if you do further development of the software

Option 2 - If you’ve just installed MySQL and haven’t set up users and databases in MySQL before:

1. Go to the command line (see OS-Specific Notes at the end of this file)
2. Make sure mysql daemon / service is running (see OS-Specific Notes at the end of this file)
3. Start the MySQL command-line client (see OS-Specific Notes at the end of

this file).

1. You should now have a ‘mysql>’ command line. Enter the following command to create the databases, as well as a user that can access them, and tighten security (substitute in your password of choice where it says <newpwd>):

        mysql> CREATE DATABASE slimarray_production;
        mysql> CREATE DATABASE slimarray_development;
        mysql> CREATE DATABASE slimarray_test;
        mysql> DELETE FROM mysql.user WHERE User = '';
        mysql> GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost' IDENTIFIED
               BY '<newpwd>' WITH GRANT OPTION;
        mysql> FLUSH PRIVILEGES;
        mysql> quit
   

This will only allow local access to all databases as the root user, which is reasonable if you’re running SLIMarray on the same computer you have the MySQL server on. For other configurations, see the documentation on the MySQL web site.

SLIMarray Rails App

You may install the SLIMarray app either by downloading a release distribution or checking it out using Subversion. The Subversion method has the advantage of being easier to update as improvements are made to the software, but may be less stable than the release distribution.

Option 1 - Install from a release:

Download a release .zip file from slimarray.systemsbiology.net/downloads. Unzip the file wherever you want the software to reside.

Option 2 - Install from Subversion repository (requires installation of Subversion):

1. Go to the command line (see OS-Specific Notes at the end of this file)
2. Change directories to where you want the software to reside (see OS-Specific Notes at the end of this file)
3. Enter ‘svn co slimarray.systemsbiology.net/svn/trunk slimarray’

Configuring SLIMarray

SLIMarray needs to be configured to connect with the MySQL databases you created. Copy the slimarray/config/database.example file to slimarray/config/database.yml. Edit slimarray/config/database.yml so that it contains the username and password that you’ve created for the production, development and test databases.

Setting up your databases

The databases you created are empty at this point, and there are two options for populating these empty databases. You can either import a default database, which has some typical user roles included, or build up the database from scratch using Rails migrations.

Option 1 - Default MySQL structure

1. Go to the command line (see OS-Specific Notes at the end of this file)
2. Change to the slimarray directory (see OS-Specific Notes at the end of this file)
3. Run ‘rake migrate’. This sets up all the database tables for SLIMarray in the development database (we’ll do the production database next).
4. Run ‘rake boostrap’. This sets up some default Users, Roles and Permissions (see the SLIMarray Administrator Guide to find out about these).
5. Do the same thing for the production database with these commands:

        rake RAILS_ENV=production migrate
        rake RAILS_ENV=production bootstrap
   

Test SLIMarray using WEBrick

LightTPD is supposed to come with FastCGI by default in newer versions, which we’ll be using WEBrick is an all-ruby web server that is built into Ruby on Rails applications. Before attempting to get the software working on a more advanced web server, WEBrick is useful in verifying that the rails application works and is communicating with the database. It’s very easy to start:

1. Go to the command line (see OS-Specific Notes at the end of this file)
2. Change to the slimarray directory (see OS-Specific Notes at the end of this file)
3. Start the server by entering ‘script/server‘
4. You should now be able to see a working SLIMarray by going to ‘localhost:3000’ in a web browser on the computer where you installed SLIMarray.
5. Log in with username ‘admin’ and password ‘admin’. You should be able to navigate around, although there is no information in the database yet so there won’t be much to see.

At this point you should have a functioning installation of SLIMarray. If you find that using WEBrick as a web server meets your needs, you can simply run it using the production database with:

        script/server -e production

If served in this way, you should be able to log in to SLIMarray from any computer on your network, by going to 'server_name':3000 (substituting in the name of your server where it says ‘server_name’.

There are some advantages to using a more advanced web server, such as speed and scalability. Using Apache as a web server is described in the next section.

SLIMarray on Lighttpd

LightTPD is a web server with good performance for Ruby on Rails applications that is easy to install. You‘ll need to follow the LightTPD’s documentation to install it. You‘ll also need to ensure that you have FastCGI support in your LightTPD install. Here are the steps to configure LightTPD to work with SLIMarray:

1. Install FastCGI (from www.fastcgi.com), and then install the ruby-fcgi gem

from source (get it at sugi.nemui.org/pub/ruby/fcgi/ruby-fcgi-0.8.6.tar.gz)

1. Edit the lighttpd.conf file (where LightTPD installs this depends upon

your operating system). There’s a template named slimarray/config/lighttpd.conf.template that you can start with. The following sections should be modidifed to relfect your particular installation:

        server.document-root        = "/srv/rails/chip_accounting/public/"

        server.errorlog          = "/srv/rails/chip_accounting/log/lighttpd.error.log"
        accesslog.filename       = "/srv/rails/chip_accounting/log/lighttpd.access.log"

        url.rewrite              = ( "^/$" => "index.html", "^([^.]+)$" => "$1.html" )

        fastcgi.server      = ( ".fcgi" => ( "localhost" => (
          "min-procs"       => 1,
          "max-procs"       => 1,
          "socket"          => "/srv/rails/chip_accounting/tmp/sockets/fcgi.socket",
          "bin-path"        => "/srv/rails/chip_accounting/public/dispatch.fcgi",
          "bin-environment" => ( "RAILS_ENV" => "production" )
        ) ) )

1. Make sure the ‘shebang’ line in slimarray/public/dispatch.fcgi is pointed

in the correct place to find ruby (it may need to be ’#!/usr/bin/ruby’ instead of ’#!/usr/local/bin/ruby’. If you’re a linux user, you can try ‘which ruby’ at the command line, and make sure what you get matches the first line of the dispatch.fcgi file.

1. This primarily applies to linux installations. Set permissions properly by

changing the group on your slimarray directory and everything under it to ‘lighttpd’.

1. Try starting the web server. If it works, you’ll be able to go to

‘localhost’ in a web browser on the server computer and access the application.

OS-Specific Notes

Getting to a command line:

• Windows - Click Start -> Run, then enter ‘cmd’ in the window that comes up
• Linux - Find out where you launch the ‘terminal’ application for your

distribution (you are probably already be very familiar with this if you installed the prerequisites of ruby, mysql and apache)

Changing directory:

• Windows - Enter ‘cd <DRIVE>:\path\you\want’, for instance ‘cd C:\rails\slimarray’
• Linux - Enter ‘cd /path/you/want’, for instance ‘cd ~/slimarray’

Making sure MySQL service / daemon is running:

• Windows - Right-click on ‘My Computer’ and choose ‘Manage‘

(this requires administrator privileges). Under ‘Services and Applications’, click on ‘Services’. Make sure the ‘MySQL’ service shows a status of ‘Started’ and startup type of ‘Automatic’.

• Linux - As root, run ‘service mysqld start’ or the equivalent command to

start MySQL Server for your Linux distribution

Starting the MySQL client for the first time:

• Windows - Click Start -> All Programs -> MySQL -> MySQL Server 5.0 -> MySQL Command

Line Client

• Linux - At the command-line, enter ‘mysql -u root’