= 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	- http://www.ruby-lang.org (Linux) or http://rubyinstaller.rubyforge.org (Windows)
* MySQL Server >= 4.2 - http://www.mysql.com/
* OPTIONAL: OpenLDAP - http://www.openldap.org
* OPTIONAL: LightTPD - http://www.lighttpd.net
* OPTIONAL: Subversion - http://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)
2. Start the MySQL command-line client (see OS-Specific Notes at the end of this file).
3. 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 http://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 http://slimarray.systemsbiology.net/svn/trunk'

== 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 and Roles (see the 
   SLIMarray user guide to find out about these).
5. Run 'rake sync_permissions'. This sets up some default permissions for 
   the users and roles that were created with 'bootstrap'.
   (see the SLIMarray user guide to find out about these).
6. Do the same thing for the production database with these commands:
	rake RAILS_ENV=production migrate
	rake RAILS_ENV=production bootstrap
	rake sync_permissions

== 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 
   'http://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 http://'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 
http://sugi.nemui.org/pub/ruby/fcgi/ruby-fcgi-0.8.6.tar.gz)

2. 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" )
	) ) )

3. 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.

4. This primarily applies to linux installations. Set permissions properly by 
changing the group on your slimarray directory and everything under it to 
'lighttpd'.

5. 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'