Difference between revisions of "Installation"
(→Create the database) |
(→Installation) |
||
Line 51: | Line 51: | ||
== Installation == | == Installation == | ||
− | === | + | === Stepwise overview === |
# 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. | # 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. | ||
Line 61: | Line 61: | ||
# Start the server | # Start the server | ||
− | + | === Download the 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]]]. | ||
Line 79: | Line 77: | ||
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 | ||
− | + | === 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'' (note for Ruby 1.9.1 users you will likely need to install the ruby-debug19 gem). | ||
Line 105: | Line 103: | ||
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 [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. | ||
− | + | === 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. | These instructions follow the defaults included in the database.yml file. Edit that file to change your configuration as necessary. | ||
Line 154: | Line 154: | ||
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); | ||
− | + | === Configure the local environment === | |
Open the | Open the |
Revision as of 12:41, 19 August 2011
Contents
|
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.
Dependencies
Required
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).
- 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.
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.
RubyGems
- Its easiest to install several Ruby packages (including Rails) through the Ruby package manager RubyGems.
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
Optional
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.
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
Installation
Stepwise overview
- 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.
- Create the database(s)
- Populate the database with some initial data
- Configure the local environment
- Configure your folders
- Start the server
Download the mx source
The preferred method is now to checkout the source from Sourceforge using [SVN]].
The (most) stable branch is the trunk, though it presently lags significantly behind edge (see comments in intro):
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
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
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 here, or here, and more recently here for other possible solutions if you have no luck with the above.
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 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'.
Then exit mysql and 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.
Populate the database with some initial data
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);
Configure the local environment
Open the
/config/initializers/local_config.rb
Update the various FOO variables as needed, see comments therein.
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 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
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.
files files/images files/images/big files/images/medium files/images/original files/images/thumb files/pdfs files/datasets files/chromatograms
On a *nix syste you can also use a symbolic link to keep your images, pdfs, and datasets elsewhere.
Start the server (development)
ruby script/server
Navigate to http://127.0.0.1:3000
Troubleshooting
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;'.
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
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
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
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.
Apache configuration
If you plan to use the API functionality you'll need add the following to your virtual .conf:
AllowEncodedSlashes On
Legacy notes on installation / configuration
- 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 [Slicehost blog] (November, 2008).
- Notes for Server set up note here.