Using Puma, Rails 4 and JRuby on Heroku

The state of JRuby deployment has improved quite a bit since I wrote my book. But information on setting up a new environment still seems hard to come by. I've encountered a number of folks who have tried to set up a deployment environment using guides that are directed at MRI (C Ruby) users. Let's fix that, shall we...

In this post, I'll walk you through the basic steps for setting up Rails 4 to run with Puma under JRuby. Then you'll learn how to deploy that app on Heroku.

Creating a New App

First, let's create a brand new Rails 4 application. Make sure you have JRuby installed and are using it, like this:

Now install the Rails 4 Gem and create a new Rails application:

Because this application was created under JRuby, a nice set of defaults have been configured for you. Gems like "therubyrhino" and "activerecord-jdbc" are already in your application's Gemfile.

But the new application does not have a production ready web server. That's were Puma comes in.

Using and Configuring Puma

Move into the root directory for your new application and open the Gemfile. You'll probably see a commented out line for the "unicorn" gem. Delete it. JRuby and Unicorn are a bad combination (if they even work together at all).

Now add the following line to the Gemfile to make Puma a dependency:

Run bundle install at the command line to install the Gem.  Then configure Puma by creating a config/puma.rb file and putting the follow code in it:

This will set the port, environment, and thread pool size based on environment variables. The defaults are intended for development.

Because Puma is a multi-threaded server, and JRuby has real threads, you'll want to configure your database connection pool size appropriately. To do this, create a config/initializers/database_connection.rb file, and put the following code in it:

Setting your maximum pool size to the number of threads is a good default.

Now run the application with this command:

Your application is running, and you can see it by browsing to http://localhost:3000. You'll probably get an error if you haven't connected the application to a database. You can do that locally, or you can use a free one from Heroku.

Deploying to Heroku

Heroku is a Platform-as-a-Service that supports both Ruby and Java applications. Naturally, it also supports JRuby. To start using Heroku, follow this guide for installing the Heroku toolbelt and creating an account. This will provide you with a heroku command that you can use to create and deploy apps for free!

To start, make sure your project is under version control with Git by running these commands:

Now you need to tell Heroku how to run your app. Do this by placing the command you ran earlier in a Procfile in the root directory of your project. Create the Procfile and put this code in it:

You'll also need to configure the Ruby runtime in your Gemfile (in this case its JRuby) by adding this line:

Add the changes to Git by running these commands:

Next, create a Heroku app for the project and make your first deployment by running these command:

Heroku has detected that your application uses JRuby, it installed the JDK, ran bundler and launched your web process. If you were to open the app by running heroku open you'll probably get an error, because the default landing page is disabled in this environment. But you can create standard Rails templates by running rails generate controller welcome as you would with MRI.

There is a great deal more that Heroku can do for you. You can provision a database, a queuing system, a scheduler, monitoring tools, or even telephony services. And of course, you can begin to leverage the power of the JVM for your Ruby app.

You can download the complete source code for the application presented in this article from the heroku-jruby-rails-4 repo on Github.