Like many of you, I was excited about the announcement regarding Heroku at Dreamforce.  I wanted to learn more about Ruby and Heroku and what better way to learn a new programming language than to write and deploy an application.  Though I found the getting started article useful, it assumes you have a working environment.  This article shows you how you can easily setup a working environment on a windows machine. 

The Big Picture

Before we get started, it is useful to understand how the toolkit fits into the overall Ruby environment. Ruby is a programming language  and Rails is a web application framework.  The Force.com toolkit for Ruby is a library (called a gem in Ruby parlance) that speaks to the Force.com database via the Web Services API.  Ruby provides several tools like gem for package management and rake a build program similar to make.  

Setting up the Ruby on Rails environment

The first step is to install Ruby.  I downloaded and installed from  this site – http://rubyinstaller.org/downloads/ .  Run the executable and choose the installation option to add Ruby executable to your path.  I installed it in c:softwareRuby192

Next, open a command window and follow the steps below.  We will be installing various libraries needed to setup our environment.

•  Install rake.  We will need it later.

    c:softwareRuby192 >  gem install rake

• Install Rails.  We explicitly specify version 2.3.8 since the toolkit was built against that version.

    c:softwareRuby192 >  gem install -v=2.3.8 rails

•  Install hpricot as below.  I had to specify the platform flag since I got an error without it.  

    c:softwareRuby192 >  gem install hpricot –platform=mswin32

• Install Facets.

    c:softwareRuby192 >  gem install -v=2.8.4 facets

• Install the Force.com Ruby toolkit

    c:softwareRuby192 >  gem install asf-soap-adapter

At this point we have the necessary environment to create a Rails project that uses the Force.com toolkit.  Let us test it by creating a new project and making sure that everything is setup properly.

Testing the toolkit 

We start by creating a new rails project

c:softwareRailsExamples > rails test

This creates a new project under the directory test.  We would need to modify two of the files that Rails creates for us.

• configenvironment.rb – Add the reference to the Force.com toolkit.  Your file should look like  this environment.rb file.
• configdatabase.yml – you need to specify your org credentials.  Add a configuration element called salesforce-default-realm.  The final file should look like this database.yml file.  Do not forget to add the security token to the password element. 

We are now ready to test the connectivity.  Open a command window and go to the root of your project directory.  We will start the console to do our test.

c:softwareRailsExamplestest > ruby scriptconsole

You will now be able to call the different methods in the toolkit.  Let us do a simple query by typing the following in the console.

>> Salesforce::SfBase.query_by_sql("select name from Account") 

If everything is setup correctly, you should see a list of the accounts in your org.  

Congrats!  You now have a working environment to start building your Rails applications that leverages Force.com.

What next?

• Download the example referenced in the wiki article.  You can either download the source or use git a distributed source code control tool.  You can find more information on git and github here.
• Examine the source of the Force.com toolkit – especially sf_base.rb an sf_utility.rb to get an idea of the methods available.  The toolkit is available  here on github.
• Build your own application and deploy on Heroku.  I will be examining this in a later blog.  

I hope this blog saves you some time as you begin your Ruby journey with Force.com and database.com.  I am excited about the possibilities. Finally, I would like to thank my friend Ray Gao for helping me with some of the issues I ran into while building my first Ruby app.