Difference between revisions of "Installation"

From mx Help Wiki
Jump to: navigation, search
m (→‎Build the database)
Line 79: Line 79:
  
 
   ruby -v
 
   ruby -v
−
 
−
 
  
 
* Some instructions for compiling [http://www.imagemagick.org/ ImageMagick] and its dependencies can be found [http://ariejan.net/2007/05/29/installing-rmagick-ruby-gem-on-mac-os-x-1049/ 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.
 
* Some instructions for compiling [http://www.imagemagick.org/ ImageMagick] and its dependencies can be found [http://ariejan.net/2007/05/29/installing-rmagick-ruby-gem-on-mac-os-x-1049/ 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.
Line 131: Line 129:
 
         create database mx_production;
 
         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'):
 
Then exit mysql and create the development database with the rake task (you may need to prefix with 'sudo'):
  
Line 141: Line 143:
 
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.
  
−
==== Add an administrator to the mx tables ====
+
==== Adding an administrator and root to the taxon tree ====
  
−
These steps all require that you are using the MySQL client
+
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  
+
         mysql -u root -p
 
         <enter password>
 
         <enter password>
−
 
−
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';
 
−
 
−
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.
 
−
 
 
         use mx_development;
 
         use mx_development;
 
         insert into people (first_name, last_name, login, password, is_admin,
 
         insert into people (first_name, last_name, login, password, is_admin,
Line 160: Line 155:
 
* IMPORTANT - you must wrap 'foo' and 'bar' around your password in the above line.  In the example above the password for 'jsmith' is 'somepwd' #
 
* IMPORTANT - you must wrap 'foo' and 'bar' around your password in the above line.  In the example above the password for 'jsmith' is 'somepwd' #
 
          
 
          
−
==== Add a root taxon name to your tables ====
+
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).
−
 
+
−
While in the MySQL client you'll also want to add a root node to your taxonomic names hierarchy (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);
 
         insert into taxon_names (name, display_name, l, r, creator_id, updator_id) values ('root', 'root', 1, 2, 1, 1);
Line 169: Line 162:
 
[[Image:Root_visible.png|400 px|Use the visibility list in the Taxon names tab to make root visible]]
 
[[Image:Root_visible.png|400 px|Use the visibility list in the Taxon names tab to make root visible]]
  
−
==== Check/update the environment.rb file ====
+
==== Configure the environment.rb file ====
  
−
Check the  
+
Open the  
 
    
 
    
 
   /config/environment.rb  
 
   /config/environment.rb  
  
−
file. At the bottom you'll some variables under the header Local Configuration. Some past versions of the source have the variables incorrectly set like so:
+
file in a text editor.   At the bottom you'll some variables under the header Local Configuration.  
−
 
+
−
HOME_SERVER = foo.bar.com
+
−
 
+
−
or
+
−
 
+
−
NOTIFICATION_RECIPIENTS = foo@bar.com
+
−
 
+
−
When they should be like:
+
  
 
  HOME_SERVER = 'foo.bar.com'
 
  HOME_SERVER = 'foo.bar.com'
−
 
−
and
 
−
 
 
  NOTIFICATION_RECIPIENTS = 'foo@bar.com'
 
  NOTIFICATION_RECIPIENTS = 'foo@bar.com'
  
Line 224: Line 206:
 
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.
 
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 mode) ==
+
== Usage (development) ==
  
 
=== Using the server/application ===
 
=== Using the server/application ===
Line 250: Line 232:
 
to add regular users.
 
to add regular users.
  
−
=== Rebuilding the tables ===
+
== Usage (production) ==
  
−
If you've downloaded a new version of mx, or have a new copy of the tables you can rebuild the tables several ways.
+
<under construction>
  
−
==== Using rake ====
+
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.
  
−
Navigate to /db and do
+
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.
  
−
rake --tasks
+
=== Configuration ===
  
−
You'll see a list of options that you can run in that directory. The dumped data goes into /dumps.<br/>
+
See the notes on config/environment.rb above, in addition you'll have to provide values for
  
−
To rebuild the tables with the *current* data do this
+
    HOME_SERVER
−
 
+
    HELP_WIKI
−
rake reload
+
−
 
+
−
So if you have acquired a copy of data from someone else you can do something like this:
+
−
 
+
−
  rake restore file=<your file like 2007_01_10_173343.sql>
+
−
 
+
−
Note that its assumed that the data is in /dumps.
+
−
 
+
−
==== Using SQL statements ====
+
−
 
+
−
If you just want to rebuild the tables (*prior* to their being any data, all data will be LOST via this method) you can repeat the building commands:
+
−
 
+
−
cd <trunk>/db
+
−
mysql -u <username, e.g. root> -p
+
−
drop database mx_development;
+
−
create database mx_development;
+
−
use mx_development;
+
−
source tables.sql;
+
−
 
+
−
If you have data that you want to maintain then do a
+
−
 
+
−
rake dump_data
+
−
 
+
−
prior to the sequence above.  Then repeat the rake restore.
+
−
 
+
−
== Usage (production mode) ==
+
−
 
+
−
<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.
+
  
−
Configuration:
+
and replacing the emails in
−
You will have to change some values in config/environment.rb, such as HOME_SERVER, HELP_WIKI and replacing the emails in
+
 
−
ExceptionNotifier.exception_recipients = %w(joe@schmoe.com bob@gmail.com)
+
    ExceptionNotifier.exception_recipients = %w(joe@schmoe.com bob@gmail.com)

Revision as of 15:13, 19 July 2008

Contents

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. 4.1.10 and previous will load, but several queries (mostly Matrix related) will not work. We have not investigated whether they can be modified to work with 4.1.10 or earlier. 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. You'll want to secure your mysql installation.
  • 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.82 or 1.84. We recommend building it from source. Get it the source here.

RubyGems

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

Rails

Source is now posted for 2.02.

Do: 

 gem install rails --include-dependencies

More information on installing Rails may be found at the URL above. Production is now using 2.0.2.

You'll also need RedCloth, a simple markup language that is used in various places (sudo these on OS X). 

  gem install redcloth

and the mysql adapter 

  gem install mysql

and ruby-debug 

  gem install ruby-debug

ImageMagik (optional)

  • NOTE: This is optional, and not required for MorphBank images.
  • The tools 'convert' and 'identify' must be in your PATH.

Platform Specific Notes

OS X

  • 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 is 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. 
gem install rails --include-dependencies
  • 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 have to use 'sudo' in front of your commands when installing, like 
sudo gem install rails --include dependencies


  • You need to be running Ruby version 1.8.2 or higher (tested on 1.8.2)
  • OS X updates **WILL** break your installation by (re)installing Ruby to /usr/bin. Their version (at least in 10.3.9) is incompatible with mx. The easiest way to get around this is to simply rename the OS X version ruby in /usr/local/bin to something like ruby_old like this: 
cd /usr/local/bin
mv ruby ruby_old
  • Test your version of ruby at the path by entering 
  ruby -v
  • 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.

x86 (Windows 2000/XP)

  • you will need to install the ruby-debug gem (the latest version doesn't? have a pre-compiled binary, this version does) 
   gem install ruby-debug -v 0.9.3
  • The db/rake tasks for rebuilding are apparently borked at present matt 19:40, 16 January 2007 (CST)

*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


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

Its always worthwhile contacting the developers to see if you have the latest version of the source. SVN access will happen, likely in 08, until then give us a 'holler.

  1. Get it from [Sourceforge] *OR*
  2. Check out a copy via SVN (only available to developers at present)

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. Use the visibility list in the Taxon names tab to make root visible

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. 

HOME_SERVER = 'foo.bar.com'
NOTIFICATION_RECIPIENTS = 'foo@bar.com'

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

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.

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.

Configuration

See the notes on config/environment.rb above, in addition you'll have to provide values for 

   HOME_SERVER
   HELP_WIKI

and replacing the emails in 

   ExceptionNotifier.exception_recipients = %w(joe@schmoe.com bob@gmail.com)
Retrieved from "http://mx.phenomix.org/index.php?title=Installation&oldid=2036"
Personal tools