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.
- 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.
- Add the torquebox-server gem (with the same version used here) to your Gemfile, as shown in the Gemfile example in this gist.
- Replace the
web:entry in your Procfile with the long one shown in this gist.
- Update the Heroku JAVA_OPTS, as shown below.
- 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 irc.freenode.net, 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.
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.
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.