First off, I am a big fan of Jeff Douglas and all that he has done for the Salesforce community. I am constantly getting really useful stuff from his blog. That was why I was so excited to see a post he did this month about getting a sample Ruby on Rails Force.com Canvas App.
I have been playing with Ruby, Node.js, and Heroku for several weeks now, so this seemed like a great thing for me to install and check out. The problem was that I ran into quite a few issues while trying to get the app working (primarily because I am trying to do all this on a Windows machine/command line) and not a Linux or OSX shell (as Jeff was obviously using).
This post is all about the problems I ran into and what you can do to avoid them if you are trying to run this on a Windows machine. So, if you want to install Jeff’s Sample Ruby on Rails app, first follow the great instructions on Jeff’s blog, which have you setup the connected app in your developer org.
For the next section about installing the rails-canvas app, if you are running all this on a Windows machine, you will want to consider the following when completing that section:
- You will need to already have Ruby running on your machine. But, you will specifically need to be running an older version of it in order to get this particular tutorial to work. I already had the newest version of Ruby (2.0) running on my machine, but I found out that it would not work until I used a particular older version (1.9.3) that is deemed more stable (especially on Windows, and even more specifically on a Windows 64bit machine, as I am using). Specifically, I was not able to start the rails server, without getting an error with the eventmachine. I imagine, you might be able to get around this eventually (even though I tried several things), but I think the easiest way is to just use the more stable version of Ruby.
- To install Ruby on Windows, go to the RubyInstaller web site and download the Ruby 1.9.3-p545 version specifically. If you already have the latest version of Ruby running on your machine, you will either need to uninstall that version or use a Ruby version manager tool (such as rvm for Linux or Pik for Windows) to specify that you need to be running the older version of Ruby.
- If you do not already have Git (which is an open source code versioning application) installed on your Windows machine, you will need to install this first in order to get the source code required for this demo. To do that on a Windows machine, you will want to go to the GitHub page to download the installer for the msysGit project. I would also recommend installing GitExtensions for Windows, as it makes it much easier (via a GUI) to clone (aka, copy) GitHub projects to a Windows machine.
- Once Git is installed, you will need to use either GitBash (which is installed on your Desktop by default with msysGit) or GitExtensions (as seen in the picture on the right) to clone the sample code that Jeff has provided on GitHub.
- Once the project is cloned to your local machine, you will need to open a command prompt and change directories to the directory where your project files are located. You will then need to bundle the project (which will install any of the gems this project requires). This is done by issuing the following commands from the command prompt (as seen in the image below).
cd/ cd apps/rails-canvas bundle
- You will now need to return to Jeff’s post and follow the instructions to get the Consumer Secret for your connected app. Once you have this secret number, you will need to add it as an environment variable. In Windows, this is done using the Set command from the command window. Jeff’s post refers to the export command, but this is specific to the Linux environment. In Windows, you will just change the command to be “set” instead of “export”, and “YOUR_SECRET” will be the numeric code you retrieve from Salesforce, such as the following:
- Now this step is something Jeff’s post does not refer to, but is VERY important if you want to get this tutorial to work. If you were to proceed at this point with Jeff’s instructions, you could start the server, tunnel through port 443 to 3000 and even start your Canvas app, but you would probably get a connection failed error in your browser. The error is caused by the fact that the OpenSSL library that Rails installer uses has no certificate authorities defined by default. Yes, you “could” get around this by changing a line of code in the Gemfile to use http and not https, but that would defeat the whole purpose of this tutorial, since Canvas requires https. So, to fix this, you will need to download a certificate (cacert.pem) and install it on your local machine. Follow the steps in this GitHub Gist post to do that. I imagine Jeff did not mention this because he has been working with this stuff for so long, he probably installed a cert file on his machine two years ago.
- You will then need to start the Rails server, which you can do from the Windows command prompt. You do this by entering “rails s” or “rails server” from the command prompt.
- Jeff’s post instructs you to use sudo to run the tunnels command, but this is a linux command and will mean nothing to you Windows users. Alternatively, you will need to fire up another instance of the Windows Command Prompt, but do so by right-clicking on the app and selecting, “Run as Administrator”. This essentially does the same thing that the sudo command does. From there just enter “tunnels 443 300” (as I did in the screenshot on the right).
- From there, you will want to open your browser and go to the https:/localhost/canvas page and click the “Understand the Risks” button that you should be presented with.
- Finally, you can go back to Salesforce and browse to your Sample Canvas app (either using the Chatter tab) or by going to the Canvas App Previewer (as seen below).
Now, I realize with all these steps, you might be thinking, “Why the Heck bother?” I hear ya!
But, there is something very powerful in understanding how to do all this. Salesforce and the Force.com platform will only be powerful if you are able to interact with it as seamlessly as possible and Canvas apps offer a GREAT way to do this. I hope you are able to get it working using the steps in this post and you do not waste two days (as I did). :-)