Of course the first step is to install the Java JDK. Download, install and then set it up in your path. I'm using JDK 6 update 21 on Linux for this post in case it matters.

There are a couple ways to install JRuby after you have Java installed. The hard way is to download JRuby and install it by hand. The easy way is to use Ruby Version Manager to install it. Using RVM will let you switch between Ruby versions as well as giving you a simple command to install JRuby:

rvm install jruby
rvm use jruby

At this point you should be able to run a test JRuby application and install gems in the JRuby environment. The next step is to install a few gems. Those gems are mizuno, rack and sinatra:

gem install mizuno rack sinatra

Of these three packages the one that you may not have heard about is mizuno. Mizuno runs a Java based web container called Jetty and will allow you to easily run rack based JRuby apps easily. Beyond the ease of running Rack apps mizuno is also very fast but for this post the main thing is that it gives you a very easy way to get the sinatra application up and running without a lot of work.

You now have all the basics installed and it is time to create a simple sinatra app. Start by creating a file named myapp.rb with the follwing in it:

require 'sinatra/base'

class MyApp < Sinatra::Base
  get '/' do
    'Hello world!'
  end
end

This is a very simple sinatra application that will display "Hello world!" whenever you get the root URL. Check out the sinatra intro for more information about sinatra if you aren't already familiar with it.

Next you will need to create a rack configuration file named config.ru in the same directory as your myapp.rb file:

require 'rubygems'
require 'myapp'

MyApp.run! :host => 'localhost', :port => 8080

The above configuration tells rack to run the simple MyApp application on localhost:8080.

Now you are ready to start the application with mizuno. In the same directory as the config.ru and myapp.rb file run the following command:

mizuno

Something like the following should be displayed on the console after running the command:

== Sinatra/1.0 has taken the stage on 8080 for development with backup from WEBrick
[2010-10-04 21:04:06] INFO  WEBrick 1.3.1
[2010-10-04 21:04:06] INFO  ruby 1.8.7 (2010-09-28) 1
[2010-10-04 21:04:06] INFO  WEBrick::HTTPServer#start: pid=26276 port=8080

Now if you connect to localhost:8080 with a web browser you will see "Hello world!" To stop the mizuno server just hit ctrl-c. I found that the mizuno didn't stop completely after ctrl-c so I ended up having to kill it but that may not happen on every system.

At this point you are able to make simple applications with sinatra and JRuby but you won't want to stop there. Your next step will be to use a database. For database access I decided to use DataMapper on top of SQLite. If you aren't familiar with DataMapper check out the DataMapper getting started guide. Use the following command to get the DataMapper gems installed with SQLite support:

gem install dm-core dm-migrations dm-sqlite-adapter

The following code adds a DataEntry model and two routes to the original simple application. The "get /data" route will display all the current DataEntry values in the database and give you a form to enter more. The "post /data" route will take a new entry to add to the database:

require 'sinatra/base'
require 'dm-core'
require 'dm-migrations'

class DataEntry
  include DataMapper::Resource

  property :id, Serial
  property :entry, String
end

class MyApp < Sinatra::Base
  configure do
    DataMapper::Logger.new($stdout, :debug)
    DataMapper.setup(:default, 'sqlite:///tmp/survey.db')
    DataMapper.auto_upgrade!
  end

  get '/' do
    'Hello world!'
  end

  get '/data' do
    display_value = '<ol>'
    DataEntry.all.each do |data|
      display_value += '<li>' + data.entry + '</li>'
    end
    display_value += '</ol>'
    display_value += '<form action="/data" method="POST">'
    display_value += 'Entry: <input name="entry" type="text"/><br/>'
    display_value += '<input type="submit"/>'
    display_value += '</form>'
  end

  post '/data' do
    @entry = DataEntry.create(:entry => params[:entry])
    'Entry created<br/> <a href="/data">Enter more</a>'
  end
end

I've put the entire contents of the application into one file for simplicity. With something more complex you would want to split the file up as well as use templates instead of building strings of output.

Adding templates is easy as well. The sinatra reference documentation has examples of a number of different templating engines but I'm going to use haml templates for one final example. Use the following command to install the haml gem:

gem install haml

The following code does the same thing as the last version but uses named templates, check out the haml reference for details:

require 'sinatra/base'
require 'dm-core'
require 'dm-migrations'
require 'haml'

class DataEntry
  include DataMapper::Resource

  property :id, Serial
  property :entry, String
end

class MyApp < Sinatra::Base
  configure do
    DataMapper::Logger.new($stdout, :debug)
    DataMapper.setup(:default, 'sqlite:///tmp/survey.db')
    DataMapper.auto_upgrade!
  end

  get '/' do
    haml :index
  end

  get '/data' do
    haml :data_entry, :locals => { :data => DataEntry.all }
  end

  post '/data' do
    @entry = DataEntry.create(:entry => params[:entry])
    haml :data_created
  end

  template :layout do
    "%html\n  =yield\n"
  end

  template :index do
    '%h2 Hello World!'
  end

  template :data_entry do
    "%ol\n" +
    "  - data.each do |entry|\n" +
    "    %li= entry.entry\n" +
    "%form{:action => '', :method => 'post'}\n" +
    "  Entry:\n"+
    "  %input{:type => 'text', :name => 'entry'}\n"+
    "  %input{:type => 'submit', :value => 'Create'}"
  end

  template :data_created do
    "%div\n" +
    "  Entry created\n" +
    "%a(href='/data') Enter more"
  end
end

Again, I've included everything in one file for simplicity but you would want to split this up. Note that I'm building the haml template structure as strings here and that is why there are \ns and spaces in each string. Creating separate files for each template would be the way to go in any complex application.

I had already been thinking about using JRuby before the conference as a way to show that Java on a TTYLinux box can be widely useful. One of the main drawbacks of running TTYLinux is that you have to build everything by hand and that can get complicated. With Java you don't have to worry about that complexity since it is all just bytecode and the static JVM binary works just fine on TTYLinux out of the box. I think TTYLinux on EC2 and Java could be a powerful solution.

Some of the following grew out of the requirement that you verify for a lot of the Heroku addons and verification requires a credit card. For some of these tips there are easier paths if you don't mind paying a little extra or just verifying your account.

• Configuration
• Set up a custom domain name
• Poor man's cron
• Sending mail with GMail
• Keeping your logs
• Rack works too
• Compiled gems
• Understanding dynos

Configuration

For configuration Heroku has a way but for some reason it didn't seem like the best or easiest way to do things. I started off setting up a configuration file as described in this railscast on using yaml configuration files. I took a while to dig a little more and found something similar but even better way of doing configuration with Heroku.

Set up a custom domain name

To make a more professional looking app you probably want to have a non-Heroku base domain name. They make it very easy to set that up using a CNAME DNS entry.

Poor man's cron

One of the things I ran into pretty quickly was the need to run a task once every minute. Heroku offers both cron and delayed job. The cron jobs offered are a little limited since the finest grained execution for cron is once an hour. I believe delayed jobs could be made to run every minute but the next issue with both cron and delayed job on Heroku is that they are addons that require verification.

The solution for me was to create a poor man's cron. I added a controller that would execute the task and then ran wget to hit the controller from an external server. This isn't a great solution but for testing the service it worked fine. The main note on doing this is to keep in mind that you will tie up a dyno for the length of the request, see Understanding dynos for more.

Sending mail with GMail

If you want to send email you have a number of different options on Heroku. First off it is important to note that Heroku doesn't support sending email from their systems directly but instead they support outgoing SMTP. Sending mail with the Sendgrid addon is probably the most flexible option but the GMail SMTP option is the least costly. The GMail option gives you 500 emails a day and that was plenty for my use.

Even though there is an addon for the GMail option you don't actually need to use it. Instead install the action mailer optional TLS plugin. Follow the readme to get it installed and configured. Then you put something like the following into your production.rb file:

  config.action_mailer.delivery_method = :smtp
  config.action_mailer.raise_delivery_errors = true
  ActionMailer::Base.smtp_settings = {
    :tls            => true,
    :address        => 'smtp.gmail.com',
    :port           => 587,
    :domain         => 'example.come',
    :authentication => :plain,
    :user_name      => 'support@example.com',
    :password       => 'password'
  }

Keeping your logs

One downside to Heroku is that they only retain a small portion of your logs. They indicate in their docs that they only retain 100 lines of logs. So if you want to track your log output you will need to store them outside of the service. They give two suggestions in the docs for logging but there are other ways to do something similar on your own.

The solution I found that seems like the easiest is to use MongoDB to log since it is "fantastic for logging". You will need to have a MongoDB server available first. If you don't want to install MongoDB on your own external server you can try the new MongoDB hosted solution.

Once you have the MongoDB server ready you will need to add the MongoDB gem to your .gems file:

mongodb-mongo --source gems.github.com

Then you will want to install the mongo db logger plugin in your rails project. Just follow the instructions they give on the project page to get it installed.

Your app/controllers/application_controller.rb will look something like this:

class ApplicationController < ActionController::Base
  include MongoDBLogging

  helper :all # include all helpers, all the time
  protect_from_forgery # See ActionController::RequestForgeryProtection for details
end

After you get the plugin installed you will have to hard code the MongoDB information into the plugin. This could probably be fixed and pulled out of a configuration file but it won't work the way it is set up out of the box. Edit the file vendor/plugins/mongo_db_logger/lib/mongo_logger.rb and change the db_configuration to match your setup. It should be something like this:

  db_configuration = {
    'host'    => 'my.mongohost.com',
    'port'    => 56700,
    'database'    => 'testapp',
    'capsize' => default_capsize}

Now you should be able to deploy to Heroku and see your logs show up in your MongoDB database.

A couple very important things to note are that this logging won't catch exceptions that happen above the application itself and if your MongoDB server goes down your app may hang trying to connect to it.

Rack works too

You aren't limited to just Ruby on Rails with Heroku, rack works as well. That opens the door for other frameworks like Sinatra, Merb and Camping on Heroku. It is also possible that more in depth logging could be done using clogger or even rack a mole.

Here is an example Camping application:

The .gems file:

camping

The config.ru file:

require 'hello'
run Rack::Adapter::Camping.new(Hello)

The hello.rb file:

require 'camping'

Camping.goes :Hello

module Hello::Controllers
  class Index < R '/'
     def get
        render :hello
     end
  end
end

module Hello::Views
  def hello
     p  "Hello World!"
  end
end

Compiled gems

Heroku also lets you use gems that need to be compiled before they are installed. You can see this if you try to use something like memprof however you will also notice that in the memprof case it won't actually work because there are missing libraries. So using gems that require libraries may be hit or miss.

If you are lucky you may find that the gem is already part of Heroku like RMagick is. Here is a little example of using Heroku and the RMagick gem to produce an image using Camping:

The .gems file:

camping
rmagick

The config.ru file:

require 'hello'
run Rack::Adapter::Camping.new(Hello)

The hello.rb file:

require 'camping'
require 'RMagick'

Camping.goes :Hello

module Hello::Controllers
  class Index < R '/'
     def get
       @headers["Content-Type"] = "image/gif"
       img = Magick::Image.new(200, 200)

       gc = Magick::Draw.new
       gc.gravity = Magick::CenterGravity
       gc.pointsize = 32
       gc.font_family = "Helvetica"
       gc.font_weight = Magick::BoldWeight
       gc.stroke = 'none'
       gc.annotate(img, 0, 0, 0, 0, "Hello world!")

       img.format = "GIF"
       img.to_blob
     end
  end
end

Understanding dynos

It is important to understand how dynos work. The bottom line is that you need one for every concurrent request. This is easy to demonstrate with the following modification of the Camping example above:

require 'camping'

Camping.goes :Hello

module Hello::Controllers
  class Index < R '/'
     def get
        render :hello
     end
  end
end

module Hello::Views
  def hello
     sleep 10
     p  "Hello World!"
  end
end

If you deploy this application to the free version of Heroku and then open two requests to it at the same time the second request will hang until the first one completes. This should illustrate why it is important to keep your processing quick and have enough dynos to match the concurrent request needs of your application.