Difference between revisions of "Installation"

From mx Help Wiki
Jump to: navigation, search
m (Get the required gems)
(Get the required gems)
 
(43 intermediate revisions by one user not shown)
Line 1: Line 1:
 
<div style="float:right;margin: 10px;">__TOC__</div>
 
<div style="float:right;margin: 10px;">__TOC__</div>
 +
 +
 +
<div style="color:red;padding:1em;border:1px solid orange;text-align:center;">'''The new code base is on [https://github.com/mx3/mx github]'''</div>
  
 
== Overview ==
 
== Overview ==
  
mx can be installed locally for development or testing purposes or on a server. If you're seriously considering supporting a mx installation in your lab or workplace you should have an intermediate to advanced programmer or server admin on your team. <span style="color:red;">Because of the relatively rapid updates to mx we recommend that you consider using the edge branch.</span> Alternatively you could contact an admin of an existing installation and collaborate with them.
+
mx can be installed locally for development or testing purposes or on a server. If you're seriously considering supporting a mx installation in your lab or workplace you should have an intermediate to advanced programmer or server admin on your team. <span style="color:red;">Because of the relatively rapid updates to mx we recommend that you should presently use the edge branch.</span>
 +
 
 +
== Dependencies ==
  
== Required Software ==
+
=== Required ===
  
=== [http://www.mysql.com/ MySQL] ===  
+
==== [http://www.mysql.com/ MySQL] ====  
  
 
* MySQL 5.n is in use on development and production servers. Its easiest to install the community addition with the startup item, then reboot.
 
* MySQL 5.n is in use on development and production servers. Its easiest to install the community addition with the startup item, then reboot.
Line 13: Line 18:
 
* There are many examples of how to install and [[secure your mysql|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).
 
* There are many examples of how to install and [[secure your mysql|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).
  
* '''IMPORTANT:''' 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.
+
===== Mx specific settings =====
 +
* Typically you add settings to /etc/my.cnf.
 +
* First, check that the value of the `socket` setting matches that provided in /config/database.yml, looking something like this in the .cnf file.
 +
  [client]
 +
  socket          = /var/mysql/mysql.sock
 +
  [mysqld]
 +
  socket          = /var/mysql/mysql.sock
  
=== [http://www2.ruby-lang.org/en/20020102.html Ruby] ===
+
* Second, add the following line under the [mysqld] settings.
 +
  [mysqld]
 +
  max_allowed_packet = 32M
  
* If you don't already have Ruby (most *nix systems come with it installed) you can find more about it [http://www.ruby-lang.org here]. We run mx under 1.8.7 and in some cases 1.8.6.  We recommend building from source.  Get it the source [http://www2.ruby-lang.org/en/20020102.html here]. Test your version of ruby at the path by entering: 
+
==== [http://www.ruby-lang.org/en/ Ruby] ====
  
ruby -v
+
* If you don't already have Ruby (most *nix systems come with it installed) you can find more about it [http://www.ruby-lang.org here]. Ruby v. 1.8.7 or higher is now required.  We recommend building from source.  Get the source [http://www.ruby-lang.org/en/ here].
  
Under Debian 5 (installing 1.8.7 as of 2010-09-28) use
+
==== [http://docs.rubygems.org/read/chapter/3 RubyGems ] ====
sudo apt-get install ruby
+
  
=== [http://rubygems.org/read/chapter/ RubyGems ] ===
+
* Its easiest to install several Ruby packages (including Rails) through the Ruby package manager RubyGems.
  
* Its easiest to install several Ruby packages (including Rails) through the Ruby package manager RubyGems.
+
''<span style="color:red;">IMPORTANT</span>: There are issues with the rubygems > 1.7.2 and mx, the last known rubygem version to work is 1.7.2.''  This issue (and many others) should disappear when we finish the jump to Rails 3.  A possible ''untested'' workaround is to use Rails 2.3.12.
  
=== [http://www.rubyonrails.org/ Rails] ===  
+
==== [http://www.rubyonrails.org/ Rails] ====  
  
 
''' Production is now using Rails 2.3.10.  Install the required version with the -v flag.  '''
 
''' Production is now using Rails 2.3.10.  Install the required version with the -v flag.  '''
Line 34: Line 46:
 
* Do (appending --no-rdoc will speed things up, but not install local documentation):
 
* Do (appending --no-rdoc will speed things up, but not install local documentation):
  
   gem install rails --include-dependencies --no-rdoc
+
   gem install rails -v=2.3.10 --include-dependencies --no-rdoc
  
== Optional Software ==
+
=== Optional ===
  
=== [http://www.imagemagick.org/script/index.php ImageMagik] ===
+
==== [http://www.imagemagick.org/script/index.php ImageMagik] ====
  
 
* NOTE: This is optional, and not required for MorphBank images.
 
* NOTE: This is optional, and not required for MorphBank images.
Line 45: Line 57:
 
* If possible install the additional jpg, tiff, png, and gs libraries before installing ImageMagick, this will let you handle additional image formats.
 
* If possible install the additional jpg, tiff, png, and gs libraries before installing ImageMagick, this will let you handle additional image formats.
  
=== Passenger ===
+
==== Passenger ====
  
 
* Used only on a production server.
 
* Used only on a production server.
Line 51: Line 63:
  
 
   PassengerTempDir /some_other_tmp_dir
 
   PassengerTempDir /some_other_tmp_dir
 
== Legacy notes on installation ==
 
 
* These notes: [[one person's experience with installing mx]] also include Mac install instructions, but these do not include Ruby install instructions.
 
* Very good installation notes for Ubuntu hardy can be found on the [[http://articles.slicehost.com/2008/4/30/ubuntu-hardy-ruby-on-rails Slicehost blog]] (November, 2008).
 
  
 
== Installation ==  
 
== Installation ==  
  
=== Basic steps ===
+
=== Stepwise overview ===
  
# Install the required software (see above).
+
# Install the required software (see above).  There are numerous external sites that will help with installing these software, as such their installation is not documented here.
 
# Download the mx source and required gems.
 
# Download the mx source and required gems.
# Build the database(s).
+
# Create the database(s)
# Configure the database for startup.
+
# Populate the database with some initial data
 +
# Configure the local environment
 
# Configure your folders
 
# Configure your folders
 
# Start the server
 
# Start the server
  
=== Detailed installation steps ===
+
=== Download the mx source ===
 
+
==== Download mx source ====
+
  
 
The preferred method is now to checkout the source from [http://sourceforge.net/projects/mx-database/ Sourceforge] using [[http://subversion.tigris.org/ SVN]]].   
 
The preferred method is now to checkout the source from [http://sourceforge.net/projects/mx-database/ Sourceforge] using [[http://subversion.tigris.org/ SVN]]].   
  
The (most) stable branch is the trunk, though it presently lags significantly behind edge (see comments in intro):
+
<em>The (trunk) branch is now permanently deprecated, ignore it.</em> 
 
+
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:
 
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:
Line 86: Line 90:
 
   svn co https://mx-database.svn.sourceforge.net/svnroot/mx-database your_local_folder_name_here
 
   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 [[https://sourceforge.net/project/showfiles.php?group_id=175927 packages of the source]], though expect these to lag significantly behind the svn versions.
+
=== Get the required gems ===
  
==== Get the required gems ====
+
Depending on the checkout you downloaded you might need to install the ruby-debug gem ''first'' (note for Ruby 1.9.1 users you will likely need to install the ruby-debug19 gem).
 
+
Depending on the checkout you downloaded you might need to install the ruby-debug gem ''first''.
+
  
 
  ''sudo'' gem install ruby-debug
 
  ''sudo'' gem install ruby-debug
Line 98: Line 100:
 
  ''sudo'' rake gems:install
 
  ''sudo'' rake gems:install
  
To install the bioruby gem you can do:
+
==== Mysql ====
 
+
''sudo'' gem install bio
+
  
<span style="color:red;">'''Note that the native mysql gem is nearly always problematic, and you might have to work at getting it installed.'''</span>   You can try:
+
<span style="color:red;">'''Note that the native mysql gem is nearly always problematic, and you might have to work at getting it installed.'''</span>  
 +
You can try:
  
 
   sudo env ARCHFLAGS="-arch i386" gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config
 
   sudo env ARCHFLAGS="-arch i386" gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config
Line 115: Line 116:
 
  sudo gem install mysql
 
  sudo gem install mysql
  
See [http://wonko.com/post/how-to-install-the-mysqlruby-gem-on-mac-os-x-leopard here], or [http://www.macruby.org/trac/wiki/Troubleshooting here], and more recently [http://techliberty.blogspot.com/ here] for other possible solutions if you have no luck with the above.
+
See below or [http://wonko.com/post/how-to-install-the-mysqlruby-gem-on-mac-os-x-leopard here], and more recently [http://techliberty.blogspot.com/ here] for other possible solutions if you have no luck with the above.
  
==== Build the database ====
+
==== mx on 64 bit Mavericks ====
  
As of 0.2.1590 mx is setup to use the Rails migrations.
+
4/3/2014 - . Using RVM with both Ruby 1.8.7 andMysql 5.1.73 installed in 64 bits, it is possible to use the mysql2 gem + activerecord-mysql2-adapter (0.0.3).  You will have to edit the line around 30 in /trunk/vendor/plugins/redhillonrails_core/lib/red_hill_consulting/core/active_record/base.rb like so: ' column.case_sensitive = true # index.case_sensitive?'.  To install under RVM you'll need gem version 1.8.24. Force the install.  You'll have many deprecation warnings when starting the server, these can be ignored..
 +
' .  If you have lots of Specimen data you may need to add 'max_allowed_packet = 32M' in the [mysqld] section of your my.cnf.
 +
 
 +
=== Configuring the database ===
 +
 
 +
==== Create the databases ====
 +
 
 +
These instructions follow the defaults included in the database.yml file.  Edit that file to change your configuration as necessary.
  
 
If you haven't yet create the databases (don't forget the ';' for mysql  
 
If you haven't yet create the databases (don't forget the ';' for mysql  
Line 136: Line 144:
 
Repeat the above but swap out the word development for 'test' and 'production'.
 
Repeat the above but swap out the word development for 'test' and 'production'.
  
Then exit mysql and create the development database with the rake task (you may need to prefix with 'sudo'):
+
==== Build the tables and populate some initial data ====
 +
 
 +
<div style="text-align:center; color:green;">''Do this step if you have are starting from scratch, and have no existing mx dump to work with.  If you have a mx data dump (see below) skip to "Import existing data".''</div>
 +
 
 +
Exit mysql and navigate to the root of your mx install. Create the development database with the rake task (you may need to prefix with 'sudo'):
  
 
         rake db:migrate RAILS_ENV=development
 
         rake db:migrate RAILS_ENV=development
Line 147: Line 159:
  
 
         rake db:test:clone_structure
 
         rake db:test:clone_structure
 
  
 
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| rake tasks available for dumping and restoring data]], make sure to check them out.
 
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| 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.
 
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.
Line 167: Line 176:
 
         insert into taxon_names (name, cached_display_name, l, r, creator_id, updator_id) values ('root', 'root', 1, 2, 1, 1);
 
         insert into taxon_names (name, cached_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.
+
==== Importing existing data ====
[[Image:Root_visible.png|400 px|Use the visibility list in the Taxon names tab to make root visible]]
+
  
==== Configure the environment.rb file ====
+
If you have access to an existing dump of mx data (it will look something like "2011_08_19_110700.sql") generated by you or an existing mx adminstrator, then you need not do the 'Build the tables and populate some initial data' step.  To use this data copy the .sql file ''mx_root''/db/dumps, then do this
  
Open the
+
        rake mx:db:restore_last RAILS_ENV=development
 
+
  /config/environment.rb
+
  
file in a text editor.  At the bottom you'll some variables under the header Local Configuration. Provide values for:
+
This will both build the database and load your data dump into it.
  
HOME_SERVER = 'your-server.com'
+
=== Configure the mx environment ===
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.
+
If you are starting with a new mx, i.e. not a version in production somehwere, you'll need to configure the local environment.
 +
 
 +
Open
 +
 
 +
  /config/initializers/local_config.rb
  
You may also change the various FOO_PATHs if your local configuration is setup differently.
+
and update the various FOO variables as needed, see comments therein.
  
You'll need to grab [http://code.google.com/apis/maps/signup.html GoogleMaps API keys] and add them for BOTH of:
+
You'll need to grab [http://code.google.com/apis/maps/signup.html GoogleMaps API keys] and add them to BOTH of:
  
 
   GMAPS_KEY_PRODUCTION
 
   GMAPS_KEY_PRODUCTION
Line 195: Line 204:
  
 
with those you want e-mails to be sent to when errors are thrown.
 
with those you want e-mails to be sent to when errors are thrown.
 +
 +
=== Configure your operating system environment ===
  
 
==== Specific to *nix systems: check the path of your MySQL socket ====
 
==== Specific to *nix systems: check the path of your MySQL socket ====
Line 210: Line 221:
 
=== Configuring file and image storage ===
 
=== Configuring file and image storage ===
  
Edit the /config/initializers/local_config.rb file and configure the various FILE_PATH variables, they can be left is if needed.  If left is they correspond to the folders that you'll need to create below in the /public folder.
+
Edit the /config/initializers/local_config.rb file and configure the various FILE_PATH variables, for development they can typically be left alone.  If left as-is they correspond to the folders that you'll need to create as below:
  
         files
+
         public/files
         files/images
+
         public/files/images
         files/images/big
+
         public/files/images/big
         files/images/medium
+
         public/files/images/medium
         files/images/original
+
         public/files/images/original
         files/images/thumb
+
         public/files/images/thumb
         files/pdfs
+
         public/files/pdfs
         files/datasets
+
         public/files/datasets
         files/chromatograms
+
         public/files/chromatograms
  
On a *nix syste you can also use a symbolic link to keep your images, pdfs, and datasets elsewhere.
+
On a *nix system you can also use a symbolic link to keep your images, pdfs, and datasets elsewhere.
 +
 
 +
=== Test your configurations/environment ===
 +
 
 +
Do
 +
 
 +
  rake test
 +
 
 +
This runs the numerous internal tests, it take some time.  While you'll typically see a few fail the vast majority should pass.  If they do chances are your environment is correctly configured.
  
 
=== Start the server (development) ===
 
=== Start the server (development) ===
 +
 +
Try starting the sever, depending on your operating system you may have to set some permission.
  
 
  ruby script/server
 
  ruby script/server
  
Navigate to [127.0.0.1:3000 127.0.0.1:3000]
+
Navigate to [http://127.0.0.1:3000 http://127.0.0.1:3000]
 +
 
 +
You may see the following problems at this point (solution in []).
 +
 
 +
* <em>schema.rb doesn't exist yet. Run "rake db:migrate" to create it then try again.</em>  [Run "rake db:migrate" (and see below).
 +
* <em>Rails Error: Unable to access log file.</em> [Change permissions on the /log folder so that it is writable.  In development just do "chmod 755 log". Then, in the log folder, do "echo '' > development.log", followed by "chmod 666 development.log". If you are on a mac or linux machine you may need to prefix these commands with "sudo".]
  
 
=== Troubleshooting ===
 
=== Troubleshooting ===
Line 271: Line 297:
  
 
  rake test
 
  rake test
 +
 +
== Usage (production) ==
 +
 +
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.
  
 
=== Production with no customizations ===
 
=== Production with no customizations ===
Line 277: Line 309:
  
 
=== Production with customizations ===
 
=== 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.
 
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) ==
+
=== Apache configuration ===
  
<under construction>
+
If you plan to use the API functionality you'll need add the following to your virtual .conf:
 +
 
 +
  AllowEncodedSlashes On
  
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.
+
== Legacy notes on installation / configuration ==
 
+
   
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.
+
* These notes: [[one person's experience with installing mx]] also include Mac install instructions, but these do not include Ruby install instructions.
 +
* Very good installation notes for Ubuntu hardy can be found on the [[http://articles.slicehost.com/2008/4/30/ubuntu-hardy-ruby-on-rails Slicehost blog]] (November, 2008).
 +
* Notes for [[Server configuration | Server set up note here]].

Latest revision as of 12:00, 3 April 2014

Contents


The new code base is on github

[edit] Overview

mx can be installed locally for development or testing purposes or on a server. If you're seriously considering supporting a mx installation in your lab or workplace you should have an intermediate to advanced programmer or server admin on your team. Because of the relatively rapid updates to mx we recommend that you should presently use the edge branch.

[edit] Dependencies

[edit] Required

[edit] MySQL

  • MySQL 5.n is in use on development and production servers. Its easiest to install the community addition with the startup item, 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).
[edit] Mx specific settings
  • Typically you add settings to /etc/my.cnf.
  • First, check that the value of the `socket` setting matches that provided in /config/database.yml, looking something like this in the .cnf file.
 [client]
 socket          = /var/mysql/mysql.sock
 [mysqld]
 socket          = /var/mysql/mysql.sock
  • Second, add the following line under the [mysqld] settings.
 [mysqld]
 max_allowed_packet = 32M

[edit] Ruby

  • If you don't already have Ruby (most *nix systems come with it installed) you can find more about it here. Ruby v. 1.8.7 or higher is now required. We recommend building from source. Get the source here.

[edit] RubyGems

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

IMPORTANT: There are issues with the rubygems > 1.7.2 and mx, the last known rubygem version to work is 1.7.2. This issue (and many others) should disappear when we finish the jump to Rails 3. A possible untested workaround is to use Rails 2.3.12.

[edit] Rails

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

  • Do (appending --no-rdoc will speed things up, but not install local documentation):
 gem install rails -v=2.3.10 --include-dependencies --no-rdoc

[edit] Optional

[edit] ImageMagik

  • 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. You do not need a rubygem hook.
  • Ensure that you have created the necessary paths for storing the images.
  • If possible install the additional jpg, tiff, png, and gs libraries before installing ImageMagick, this will let you handle additional image formats.

[edit] Passenger

  • Used only on a production server.
  • If you are running passenger, on CentOS/RHEL 5 servers there is a default daily chron that deletes some necessary passenger files in /tmp/passenger.PID. The easiest way to deal with this is to set the PassengerTempDir in the apache conf to something else, like so:
 PassengerTempDir /some_other_tmp_dir

[edit] Installation

[edit] Stepwise overview

  1. Install the required software (see above). There are numerous external sites that will help with installing these software, as such their installation is not documented here.
  2. Download the mx source and required gems.
  3. Create the database(s)
  4. Populate the database with some initial data
  5. Configure the local environment
  6. Configure your folders
  7. Start the server

[edit] Download the mx source

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

The (trunk) branch is now permanently deprecated, ignore it.

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

[edit] Get the required gems

Depending on the checkout you downloaded you might need to install the ruby-debug gem first (note for Ruby 1.9.1 users you will likely need to install the ruby-debug19 gem).

sudo gem install ruby-debug

You need various Ruby gems listed in the environment.rb. The easiest way to install them all is to enter your mx folder (you should see the folders 'app', 'config' etc. if you are in the right place) and type:

sudo rake gems:install

[edit] Mysql

Note that the native mysql gem is nearly always problematic, and you might have to work at getting it installed. You can try:

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

On RHEL (after yum install mysql-devel) this worked:

gem install mysql -- --with-mysql-config=/usr/lib64/mysql/mysql_config 

On Ubuntu 9.10 (see also here) this worked:

sudo apt-get install libmysqlclient-dev
sudo gem install mysql

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

[edit] mx on 64 bit Mavericks

4/3/2014 - . Using RVM with both Ruby 1.8.7 andMysql 5.1.73 installed in 64 bits, it is possible to use the mysql2 gem + activerecord-mysql2-adapter (0.0.3). You will have to edit the line around 30 in /trunk/vendor/plugins/redhillonrails_core/lib/red_hill_consulting/core/active_record/base.rb like so: ' column.case_sensitive = true # index.case_sensitive?'. To install under RVM you'll need gem version 1.8.24. Force the install. You'll have many deprecation warnings when starting the server, these can be ignored.. ' . If you have lots of Specimen data you may need to add 'max_allowed_packet = 32M' in the [mysqld] section of your my.cnf.

[edit] Configuring the database

[edit] Create the databases

These instructions follow the defaults included in the database.yml file. Edit that file to change your configuration as necessary.

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';

Repeat the above but swap out the word development for 'test' and 'production'.

[edit] Build the tables and populate some initial data

Do this step if you have are starting from scratch, and have no existing mx dump to work with. If you have a mx data dump (see below) skip to "Import existing data".

Exit mysql and navigate to the root of your mx install. Create the development database with the rake task (you may need to prefix with 'sudo'):

       rake db:migrate RAILS_ENV=development

You can create the production database like so if necessary:

       rake db:migrate RAILS_ENV=production

To create the test database do

       rake db:test:clone_structure

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.

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, cached_display_name, l, r, creator_id, updator_id) values ('root', 'root', 1, 2, 1, 1);

[edit] Importing existing data

If you have access to an existing dump of mx data (it will look something like "2011_08_19_110700.sql") generated by you or an existing mx adminstrator, then you need not do the 'Build the tables and populate some initial data' step. To use this data copy the .sql file mx_root/db/dumps, then do this

       rake mx:db:restore_last RAILS_ENV=development

This will both build the database and load your data dump into it.

[edit] Configure the mx environment

If you are starting with a new mx, i.e. not a version in production somehwere, you'll need to configure the local environment.

Open

  /config/initializers/local_config.rb 

and update the various FOO variables as needed, see comments therein.

You'll need to grab GoogleMaps API keys and add them to 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.

[edit] Configure your operating system environment

[edit] 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 distributions do 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

[edit] Configuring file and image storage

Edit the /config/initializers/local_config.rb file and configure the various FILE_PATH variables, for development they can typically be left alone. If left as-is they correspond to the folders that you'll need to create as below:

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

On a *nix system you can also use a symbolic link to keep your images, pdfs, and datasets elsewhere.

[edit] Test your configurations/environment

Do

 rake test

This runs the numerous internal tests, it take some time. While you'll typically see a few fail the vast majority should pass. If they do chances are your environment is correctly configured.

[edit] Start the server (development)

Try starting the sever, depending on your operating system you may have to set some permission.

ruby script/server

Navigate to http://127.0.0.1:3000

You may see the following problems at this point (solution in []).

  • schema.rb doesn't exist yet. Run "rake db:migrate" to create it then try again. [Run "rake db:migrate" (and see below).
  • Rails Error: Unable to access log file. [Change permissions on the /log folder so that it is writable. In development just do "chmod 755 log". Then, in the log folder, do "echo > development.log", followed by "chmod 666 development.log". If you are on a mac or linux machine you may need to prefix these commands with "sudo".]

[edit] Troubleshooting

[edit] Configuring my.cnf

If you get a 'Mysql::Error: Got a packet bigger than 'max_allowed_packet' bytes:' you can add the following line to your my.cnf under [mysqld]: 'max_allowed_packet = 32M;'.

[edit] Usage (development)

[edit] 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.

[edit] 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

[edit] Usage (production)

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.

[edit] 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.

[edit] Production with customizations

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.

[edit] Apache configuration

If you plan to use the API functionality you'll need add the following to your virtual .conf:

 AllowEncodedSlashes On

[edit] Legacy notes on installation / configuration

Personal tools