Updated Sep 14, 2009 by igal.koshevoy
Labels:	Phase-Implementation, Phase-Deploy, Featured

DevelopmentSoftware

Software you must install to run Calagator on your machine

Software needed by Calagator Developers for local development

Read the current instructions for installing Calagator online or from the "INSTALL.md" file in the source code checkout.

...

OBSOLETE

The instructions below are obsoleted by the "INSTALL.md" linked above, but are preserved here for archival purposes.

Listed by order of installation

software	version	link	comments
git	1.6.x or above	-	a list of Git guides - if you're new to git
Ruby	1.8.6, 1.8.7, REE	http://www.ruby-lang.org	For development work, the current release of 1.8.6 or 1.8.7 is recommended, and may already be provided by your OS's packaging system. For production servers, REE (Ruby Enterprise Edition) is recommended.
RubyGems	1.3.x or above	http://rubyforge.org/projects/rubygems/	(Windows developers: If you picked the Ruby 1.8.6 One-Click Installer when installing Ruby, you already have RubyGems, but your version is obsolete. To update, just run `gem update --system`).
Rails	2.1.x	http://rubyonrails.org/	`gem install rails -v 2.1.2 --no-ri --no-rdoc`
SQLite3	see comments	http://www.sqlite.org	Everyone needs SQLite3. Windows developers see note below.
Java	1.6.x or above	http://www.java.com/getjava	Needed for Solr
Calagator source code	-	git://github.com/calagator/calagator.git	Clone the source code with git
Google geocode key	-	http://code.google.com/apis/maps/signup.html	Read the instructions in the checked-out code of Calagator in `config/geocoder_api_keys.yml.example` (optional but maps will not display without it)
Calagator database	-	-	Run `rake db:migrate db:test:prepare` to set up database and testing environment; `rake data:fetch` to populate with data from the production version. If you receive an error message about missing required gems, see the note below.
Solr	-	-	Search engine for Calagator. Use `rake solr:start` before running the Rails application to provide search capability, and `rake solr:stop` when finished. The plugin is installed as part of the Calagator checkout. Windows developers: you'll have to stop the Solr server manually until an acts_as_solr bug is fixed, the `rake solr:stop` won't work. For complete details on our Solr setup, see this thread.

Installation

Install all listed items in the order above, following any directions in the comments. At this point you'll have the Rails app ready to test. Running specs with rake spec will help confirm that everything is configured correctly. Then you're ready to start looking through the code, and working on issues listed in the tracker.

If you're new to working with Ruby on Rails, Rails Guides will help get up to speed on the framework. The Getting Started Guide also has links to Ruby programming tutorials.

Known issues

OSX 10.5 & MacPorts

Apple ships Ruby with 10.5 (and 10.4 if I remember correctly), though it is likely that you have installed MacPorts and it in turn has installed it's own version of ruby. You will run in to an issue if the ruby at /opt/local/bin/ruby and /usr/bin/ruby are different versions. The best way around this is to move one out of the way (ie sudo mv /usr/bin/ruby /usr/bin/ruby.dist) and then symlink back to the other version (ie sudo ls -s /opt/local/bin/ruby /usr/bin/ruby).

SQLite3 for Windows

Windows developers should (a) download the pre-compiled DLL version of SQLite, (b) make sure the .def, .dll are in the Path (e.g., c:\ruby\bin); (c) install the SQLite3 gem.

When downloading SQLite3 for Windows, you must download the precompiled binary that includes the DLL (currently sqlitedll-3_6_11.zip). The .exe file -- which is in a different download -- isn't used by Rails, but isn't harmful.

SQLite3 gem release 1.2.4 does not work for Windows. Therefore Windows developers should download and install version 1.2.3: gem install --version 1.2.3 sqlite3-ruby. (The developer released SQLite3 gem release 1.2.4 without a pre-compiled Windows version. The developer intends to release the next update with a pre-compiled Windows version, but is seeking help on building that compilation. See here or here. Until this is fixed, Calagator developers using Windows should use version 1.2.3.)

When installing the SQLite3 gem for Windows: after typing in 'gem install --version 1.2.3 sqlite3-ruby', you may get 3 different gem options. Select #3,(mswin32) option.

Missing required gems error

2009.03.05 If -- sometime after cloning the Calagator source code -- you get a message saying that you are missing required gems and suggesting Run 'rake gems:install', then follow that suggestion. If that suggestion does not work (you get the same error message), then install each missing gems individually. If the error message included a version number in addition to the gem name, install that version. We also suggest installing without documentation. Example: If the error message said

Missing these required gems:
  vpim
  facets  >= 2.5.0

Then run

gem install vpim --no-rdoc --no-ri
gem install facets --version ">= 2.5.0" --no-rdoc --no-ri