Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
TorqueBox on Heroku

With Heroku's JRuby support you may have already seen that you can run TorqueBox Lite on Heroku. But, that only gives you the web features of TorqueBox. What about scheduled jobs, backgroundable, messaging, services, and caching?

With a small amount of extra work, you can now run the full TorqueBox (minus STOMP support and clustering) on Heroku as well! I've successfully deployed several test applications, including the example Rails application from our Getting Started Guide which has a scheduled job, a service, and uses backgroundable and messaging.

This example uses TorqueBox 3.0.2, but the instructions may work with other TorqueBox versions.

Steps Required

  1. Create a JRuby application on Heroku, or convert an existing application to JRuby. Make sure your application works on JRuby on Heroku before throwing TorqueBox into the mix.
  2. Add the torquebox-server gem (with the same version used here) to your Gemfile, as shown in the Gemfile example in this gist.
  3. Replace the web: entry in your Procfile with the long one shown in this gist.
  4. Update the Heroku JAVA_OPTS, as shown below.
  5. Add the changed Gemfile, and changed Procfile to git, commit, and push the changes.

If all goes well after the git push your application should boot up and be running on TorqueBox. I'd suggest you use heroku logs -t during the push to keep an eye on things. If you run into any errors while TorqueBox is starting, get in touch with us via @torquebox Twitter, #torquebox on, or any other method listed on our community page and we'll help you figure things out. A list of the most common things that could go wrong and how to fix them are below.

Potential Gotchas

Out of Memory Errors

If you get an out of memory error in the PermGen space, bump up the value for "-XX:MaxPermSize=128m" in the JAVA_OPTS. If you get an out of memory error in the Heap, bump up the value for "-Xmx256m" in the JAVA_OPTS. The defaults we're using are probably a bit too conservative, but I wanted to make sure we don't exceed Heroku's soft cap of 512MB for most applications. There's a bit more overhead to the JVM memory usage than just adding together the above two values, but experiment with things and find the best values for your application.

Likewise, if the Heroku logs tell you that you've exceed the 512MB cap then you should lower one or both of the above memory values.

To keep memory usage low, I'd suggest not using the TorqueBox session store (since it stores session in-memory) or making heavy use of the Infinispan caching integration, since that is again stored in-memory by default.

Time Outs Waiting For Application to Boot

Heroku gives your application 60 seconds to come up from the time it tells the process to start. Several of the JAVA_OPTS changes are to make the JVM boot faster, but if you do see a Heroku error about boot timeout hopefully it's only every now and then. Heroku automatically tries to boot your application again and sometimes you just get a dyno that's running slower than others, so it should fix itself.

If you always get this error when booting your application, try to reduce any work being done in Rails initializers or similar things that happen during application boot.

Heroku Spins Down Idle Dynos

Heroku spins down dynos that are idle, where idle is determined by how long it has been since your application serviced an external request. When it takes that dyno down all your background processing (jobs, services, etc) will go down with it. According to Heroku's Dynos article, you can prevent this idling of dynos by paying for more than one web dyno.

Provide Feedback

Whether you try things out and everything work flawlessly or you have a problem, please let us know! There are some things we can do to improve the experience on Heroku, but we need a rough idea of the demand to help prioritize those requests versus others.

If you're just here because you want a place to host TorqueBox applications but don't want to use Heroku, check out our other Hosting Options on the wiki.

source ''
ruby '1.9.3', engine: 'jruby', engine_version: '1.7.10'
# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
gem 'rails', '4.0.2'
gem 'activerecord-jdbcsqlite3-adapter'
gem 'activerecord-jdbcpostgresql-adapter'
# Use SCSS for stylesheets
gem 'sass-rails', '~> 4.0.0'
# Use Uglifier as compressor for JavaScript assets
gem 'uglifier', '>= 1.3.0'
# Use CoffeeScript for assets and views
gem 'coffee-rails', '~> 4.0.0'
# See for more supported runtimes
gem 'therubyrhino'
# Use jquery as the JavaScript library
gem 'jquery-rails'
# Turbolinks makes following links in your web application faster. Read more:
gem 'turbolinks'
# Build JSON APIs with ease. Read more:
gem 'jbuilder', '~> 1.2'
group :doc do
# bundle exec rake doc:rails generates the API under doc/api.
gem 'sdoc', require: false
# Heroku gems
gem 'rails_12factor', group: :production
# TorqueBox
gem 'torquebox-server', '3.0.2'
heroku config:set JAVA_OPTS="-Xmx256m -XX:MaxPermSize=128m -Xss512k \
-XX:+UseCompressedOops -Dfile.encoding=UTF-8 -XX:+UseParallelOldGC \
-XX:+TieredCompilation -XX:TieredStopAtLevel=1"
web: torquebox deploy . --env=production && torquebox run --max-threads=15 -b -p $PORT -J "\-Dorg.torquebox.web.force_http_connector_start=true \-Dorg.apache.tomcat.util.LOW_MEMORY=true"

This comment has been minimized.

Copy link

@jfturcot jfturcot commented Jun 7, 2013

Thanks for this, I want to try this with the new 2x dynos since they would be a perfect match for Torquebox, but first I wanted to ask you if you did try it on a 2x? If you tried it on a 2x, did you run into any trouble or should this script run just the same? I should try it this weekend and will post my results after if anyone is interested to know how well it runs on 2x.


This comment has been minimized.

Copy link
Owner Author

@bbrowning bbrowning commented Aug 7, 2013

I have not tried this on 2x dynos, but would be interested to hear of any results.


This comment has been minimized.

Copy link

@mikepence mikepence commented Oct 2, 2013



This comment has been minimized.

Copy link

@brandonparsons brandonparsons commented Dec 9, 2013

Any differences required if using TB 3.0.1?


This comment has been minimized.

Copy link

@brightball brightball commented Feb 7, 2014

Thanks for this! Have you been able to get this to work with clustering?


This comment has been minimized.

Copy link
Owner Author

@bbrowning bbrowning commented Feb 19, 2014

I've updated the gist to work with TorqueBox 3.0.2. I haven't even attempted to get clustering to work, since as far as I'm aware Heroku does not allow dynos to communicate directly with other dynos.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment