JRuby-Enginize

About

JRuby-Enginize is a generator for Google AppEngine compliant JRuby applications. The generator currently supports Sinatra and Merb with more frameworks to come in the future. If you want to learn more about Google AppEngine, go to code.google.com/appengine and have a look at the tutorials. For more about JRuby, please go to www.codehaus.org and see what’s up running Ruby applications on a Java VM.

Prerequisites

JRuby-Enginize needs a proper JRuby installation including rake and the Google AppEngine SDK (code.google.com/appengine/downloads.html) for Java. Make sure that the AppEngine configuration tool "appcfg.sh" is in your PATH as that’s what parts of the software are wrapping.

More dependencies depend on the framework template to generate an application for, but installation of additional gems is done with tools provided by Google (so below).

Installation

The Google people worked hard to make JRuby easier to deploy than it was at the beginning, so don’t blindly trust all those blog posts and samples you’ll find but use the newest version of jruby-enginize and have a look at the Wiki page of the Google AppEngine JRuby tools (code.google.com/p/appengine-jruby/wiki/GettingStarted) to learn about the details beyond.

These are the steps for installing the Google tools plus JRuby-Enginize running on top of it to streamline your first steps:

  sudo gem sources -a http://gemcutter.org  # Only needed once!
  sudo gem install google-appengine
  sudo gem install jruby-enginize

!!Warning: As Github cancelled gem support, we moved the gem from Github.com to Gemcutter.org. If you install from Github, you will not get the newest version! See gemcutter.org/gems/jruby-enginize for details.

You also need an Google AppEngine account to actually publish your code. Without account you can still play around with the tools and run applications locally.

Using jruby-enginize

JRuby-Enginize includes is a single executable named jruby-enginize which is inspired by the rails tool for generating Rails applications. So just call

  jruby-enginize

and have a look at the options.

Here are the steps for creating and deploying a new Sinatra application:

• Register with Google AppEngine and create a new application ID.
• Generate your application with that new ID as directory name. Sample:

  jruby-enginize —template sinatra jruby-enginize

• Go to the new directory and install the missing gems first (depends on the template you have chosen):

  rake template:gems

  !!Attention: Whenever you want to install additional gems, be sure to use appcfg.rb gem provided by the Google AppEngine JRuby tools and not jgem as Google maintains a local repository per project and bundles the files to upload from that information. You will run into missing gems on the server if you bypass this! Best approach is to use a separate JRuby installation for AppEngine development to run into missing gems when running the application locally, too.

• Learn about the available rake tasks

  rake —tasks

• Try out your application locally:

  sudo rake appengine:run

• Deploy the application:

  rake appengine:deploy

  The first time you deploy your application, you will be asked for e-mail and password to confirm your upload to the server.

You can repeat the deployment whenever you want. Be sure to set the version number in the AppEngine::Rack.configure_app part of "config.ru" to a new value, when you are experimenting with an unstable version and don’t want to risk your users getting exceptions.

You can try the new version by opening e.g.

3.latest.jruby-enginize.appspot.com

and replacing "3" with the version number you want to run.

Switch the application to the new version as default (stable version) by opening

appengine.google.com/deployment?&app_id=jruby-enginize

and setting a new default available at

jruby-enginize.appspot.com

A small README with these and a few more application specific hints is generated along with the source code. Have fun.

Copyright & License

Copyright © 2009 Holtzbrinck Digital GmbH, Jan Ulbrich

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.