Installation

Installing mx

These are somewhat brief and should evolve as more people attempt to install. Feel free to add questions right here. Details about one person's experience with installing mx on his local machine (for development) are posted separately.

At present you'll need to have a fairly good understanding of Rails to develop mx, and modify it for you needs. As the project develops we hope to continue to minimize this dependency, including for instance installer scripts, and coding how-tos. If you're seriously considering supporting a mx installation in your lab or workplace at this moment you should have an intermediate to advanced programmer/server admin in your team. Note that because one instance of mx can serve multiple projects a single admin may be able to support a team of labs, so resources could be shared in that sense.

Required Software

MySQL

• You need at least MySQL 4.1.14 to install the tables. MySQL 5.n is in use on development and production servers. Its easiest to install the community addition with the startup item too, then reboot.

• There are many examples of how to install and secure MySQL on your machine available on whe world-wide web. If you are using OS X chances are you have a copy installed already (it will need configuration if you haven't already done so).

Ruby

• If you don't already have ruby you can find more about it here. We run mx under 1.86. We recommend building it from source. Get it the source here. Test your version of ruby at the path by entering:

ruby -v

RubyGems

Its easiest to install several Ruby packages (including Rails) through the Ruby package manager RubyGems.

Rails

Production is now using Rails 2.2.2. Install the required version with the -v flag.

Do (appending --no-rdoc will speed things up, but not install local documentation):

 gem install rails --include-dependencies --no-rdoc

You'll also need several other Ruby gems:

  sudo gem install RedCloth, echoe, ruby-debug, mysql, haml

Note that the native mysql adapter/gem (mysql bit above) is often fraught with problems. This works nicely on OS X intel:

  sudo env ARCHFLAGS="-arch i386" gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config

See here, or here for other possible solutions if you have no luck with the above.

ImageMagik (optional)

• NOTE: This is optional, and not required for MorphBank images.

• The tools 'convert' and 'identify' must be in your systems PATH, copying them to /usr/bin generally works.

Platform Specific Notes

OS X

• Leopard now comes with Rails pre-installed. The only issues you should have are related to 64/32 bit incompatibilities.
• Don't even bother trying to get Leopard's preinstalled MySQL to work with Rails if it's the 64 bit version. It's basically impossible at this point. Save yourself the headache, install the 32 bit version then add the mysql gem as above.

The following notes are largely legacy at this point.

• Very good instructions on installing ruby, rails, mysql, mongrel (a webserver for ruby on rails) and subversion on Mac 10.4 PowerPC or Intel machines are here http://hivelogic.com/articles/2007/02/ruby-rails-mongrel-mysql-osx/. In these instructions, Capistrano does not to be installed nor the 'MySQL Native Bindings Gem.' The instructions install Ruby version 1.8.6 which works with at least mx 0.1.1379 and later.
• These notes: one person's experience with installing mx also include Mac install instructions, but these do not include Ruby install instructions.
• You should have Apple's developer tools installed before installing mx. Later versions of OS X come with it installed, if you can do

 gcc -v 

and see 3.n or 4.n you're probably OK.

You may need sudo here:

 sudo gem install rails --include-dependencies --no-rdoc 

• Some instructions for compiling ImageMagick and its dependencies can be found here. Although the instructions lead up to installing the rmagick ruby gem, that step should not be done because it is not necessary for mx's image handling to work. Mx only requires that the commands identify and convert be accessible from your command prompt, which these instructions without the gem install step will do.

• All systems maybe have various problems installing the mysql gem. See here for some possible help.

*nix Specific Notes

The following instructions were tested on Kubuntu 7.04 and may require some modifications according to the distribution you use.
You have to install the library libmysql-ruby:

   sudo apt-get install libmysql-ruby

Very good installtion notes for Ubuntu hardy can be found on the [Slicehost blog] (November, 2008).

Installation

Basic steps

1. Install the required software (see above).
2. Download the mx source.
3. Build the database(s).
4. Configure the database for startup.
5. Configure your folders

Detailed installation steps

Download mx source

The preferred method is now to checkout the source from Sourceforge using [SVN]].

The (most) stable branch is the trunk, this is what users who want the application only should use:

svn co https://mx-database.svn.sourceforge.net/svnroot/mx-database/trunk your_local_folder_name_here

For developers or those wanting to see the latest changes an edge branch that should be relatively stable but may contain production restricting commits is here:

svn co https://mx-database.svn.sourceforge.net/svnroot/mx-database/branches/edge your_local_folder_name_here

Several site-specific branches are being added, these are not recommended as a base for new installs but do provide a lot of example code. To grab everything you can just do:

 svn co https://mx-database.svn.sourceforge.net/svnroot/mx-database your_local_folder_name_here

We will also continue occasionally to filter and provide non-svn [packages of the source], though expect these to lag significantly behind the svn versions.

Build the database

As of 0.2.1590 mx is setup to use the Rails migrations.

If you haven't yet create the databases (don't forget the ';' for mysql commands):

       mysql -u root -p
       <enter password>
       create database mx_test;
       create database mx_development;
       create database mx_production;
       

You'll need to add a MySQL account so that the app can access the database:

       GRANT ALL PRIVILEGES ON mx_development.* TO 'mx'@'localhost' IDENTIFIED BY 'MmmXxx';

Then exit mysql and create the development database with the rake task (you may need to prefix with 'sudo'):

       rake db:migrate 

You can create the production or test databases similarly like so:

       rake db:migrate RAILS_ENV=development

Anytime the source is updated just repeat the rake db:migrate and your database will be updated if there are changes. There are several rake tasks available for dumping and restoring data, make sure to check them out.

Adding an administrator and root to the taxon tree

A single user with administrator privileges will have to be manually added to the 'people' tables prior to using mx. Once this user is added additional users can be added from the mx interface.

       mysql -u root -p
       <enter password>
       use mx_development;
       insert into people (first_name, last_name, login, password, is_admin,
         creates_projects) values ('joe', 'smith', 'jsmith', sha1('foosomepwdbar'), 1,1);
       

• IMPORTANT - you must wrap 'foo' and 'bar' around your password in the above line. In the example above the password for 'jsmith' is 'somepwd' #

While in the MySQL client you'll also want to add a root node to your taxonomic names hierarchy (this assumes the admin you created has id 1).

       insert into taxon_names (name, display_name, l, r, creator_id, updator_id) values ('root', 'root', 1, 2, 1, 1);

To start adding real taxa after you create a project make this root taxon visible via the visibility view in the "Taxon names" tab. Then the root will available as the parent of the highest taxonomic level included in your taxa list.

Configure the environment.rb file

Open the

  /config/environment.rb 

file in a text editor. At the bottom you'll some variables under the header Local Configuration. Provide values for:

HOME_SERVER = 'your-server.com'
HELP_WIKI = 'hymenoptera.tamu.edu/wiki'  

To use/link to the existing help in this wiki (a good idea!) use 'hymenoptera.tamu.edu/wiki' for HELP_WIKI.

You may also change the various FOO_PATHs if your local configuration is setup differently.

You'll need to grab GoogleMaps API keys and add them for BOTH of:

 GMAPS_KEY_PRODUCTION
 GMAPS_KEY_DEVELOPMENT

Finally, replace the emails in

   ExceptionNotifier.exception_recipients = %w(joe@schmoe.com bob@gmail.com)

with those you want e-mails to be sent to when errors are thrown.

Specific to *nix systems: check the path of your MySQL socket

By default, the path of mysql.sock is set to

  /tmp/mysql.sock

However, several distribution does not use this path. To change it edit the file

  config/database.yml

and replace the 3 occurrences of

  socket: /tmp/mysql.sock

by your actual path. For instance in Ubuntu

 socket: /var/run/mysqld/mysqld.sock

Files and images uploaded to mx are stored in /public/files

If you are on a PC create the following folders in <root of mx install>/public

       files
       files/images
       files/images/big
       files/images/medium
       files/images/original
       files/images/thumb
       files/pdfs
       files/datasets

On a *nix system (including OS X) you'll need the same structure, but note that you can also use a symbolic link to keep your images, pdfs, and datasets elsewhere.

Usage (development)

Using the server/application

To test/develop in development mode navigate to the root of your installation and type

       ruby script/server

Open a web browser and browse to

       127.0.0.1:3000

You should see a login page. If you see the mx page but no login fields then you have not correctly added your administrator user.

Once logged in navigate to

       127.0.0.1:3000/admin

to create new projects.

You can also navigate to

       127.0.0.1:3000/account/signup

to add regular users.

Upgrading

Once you have mx installed upgrading should be relatively straightforward. First, make a backup of both the database and the application, we assume you know where your data reside by this point, and we assume that you know that things can go horribly wrong. After backing up replace the old source with the new (see below for comments). Then, make sure you have the required Rails/Gems (plugins are included in the source already). Finally, run the rake task to update the database like so:

rake db:migrate RAILS_ENV=<development|production>

Its always a good idea to run the test suite as well, this will give you a good idea of what possible problems you might still have.

rake test

Production with no customizations

We don't have Capistrano working, so essentially you'll have to devise your own method of rolling to production, we use an SVN checkout for now.

Production with customizations

in progress

If you have begun to build public front ends you know where your custom code resides (/public, /app/models/public, /app/controllers/public, /app/views/public), manage these as you like.

Usage (production)

<under construction>

Production installation follows, for the most part, the same installation process as above. See the Rails homepage for setting up the server. Note that only users with accounts can see data in a clean installation of mx, i.e. you must manually configure the installation to make data available to the public.

If you plan to set up a production installation of mx, it would be a good idea to read chapter 27 of Agile Web Development with Rails, second edition.