The Nice

For me for you

51 Notes & Comments

Deploying a Rails application in Tomcat with JRuby: A concise tutorial


I recently tried to deploy a Rails app in a Tomcat container, thinking it would only take a few minutes. Instead it took a few hours. After completing this tutorial, you will be able to bundle your Rails apps as .war files that can be easily dropped into most Java containers and rapidly deployed. There are tons of resources out there as to how to do this, but I haven’t found one place that explains the process plain and simply. So, here goes.

This tutorial will rely on:
  • Rails Version 2.3.2
  • Ruby Version 1.8.7
  • Apache Tomcat Version 5.5.27
  • JRuby Version 1.3.1

Let’s Get Started

Let’s get started downloading what we’ll need to get this thing working.

  1. Download and install the Apache Tomcat Core package here.
    Once you’ve completed the download, go ahead and expand the file. When you expand Tomcat, you should get something that looks like this:
    $ /apache-tomcat-5.5.27: ls
    LICENSE        RUNNING.txt    conf/          shared/        work/
    NOTICE         bin/           logs/          temp/
    RELEASE-NOTES  common/        server/        webapps/
  2. Alter permissions
    Now we’ll will need to make sure that all of the scripts in the bin directory are executable. Let’s do this by using the chmod command:
    $ /apache-tomcat-5.5.27: cd bin
    $ /apache-tomcat-5.5.27/bin:  chmod u+x *.sh
  3. Start Tomcat
    Now, let’s try to start the Tomcat server to make sure that everything is working properly. You will need to execute these commands as the root user using the sudo command.
    $ /apache-tomcat-5.5.27/bin: sudo ./
    This will start Tomcat as a daemon. You should see something like this:
    $ /apache-tomcat-5.5.27/bin: sudo ./
    Using CATALINA_BASE:   /apache-tomcat-5.5.27
    Using CATALINA_HOME:   /apache-tomcat-5.5.27
    Using CATALINA_TMPDIR: /apache-tomcat-5.5.27/temp
    Using JRE_HOME:       /System/Library/Frameworks/JavaVM.framework/Versions/1.5/Home
    Now, let’s check to make sure that Tomcat is running by opening up a browser and pointing it to http://localhost:8080. You should see a welcome page. Tomcat has been successfully installed.
  4. Download JRuby here.
    Once you download and expand JRuby you should get something like this:
    $ ~/downloads/jruby-1.3.1: ls
    COPYING       COPYING.CPL   COPYING.GPL   COPYING.LGPL  README        bin/          docs/         lib/          samples/      share/        tool/
  5. Find a nice spot for JRuby.
    I prefer putting it somewhere like /usr/local though it doesn’t really matter where you put it.
    $ ~/downloads/jruby-1.3.1: cd ..
    $ ~/downloads/: mv jruby-1.3.1 /usr/local
  6. Edit your shell profile and add JRuby to your PATH variable.
    I use BASH (the shell that comes installed by default on OSX), and TextMate as my editor but you can use pico, emacs, vi, or whatever to edit this file.
    $ ~/downloads/jruby-1.3.1: mate ~/.profile

    You should see a line in the file that looks something like this:
    export PATH= path/to/blah:path/to/another/file/bin:path/to/blah$PATH

    Go ahead and add the path to your JRuby’s bin directory to this list, so that it looks something like this:
    export PATH= /path/to/blah:/path/to/another/file/bin:/path/to/blah:/usr/local/jruby-1.3.1/bin/:$PATH

    If there isn’t already a line that looks like this, go ahead and create one. Obviously, remove all of the pseudo paths so that it looks like this:
    export PATH= /usr/local/jruby-1.3.1/bin/:$PATH

    Now, you’ll want to reload your shell.
    $ . ~/.profile

    Now, JRuby should be installed. You can check by issuing:
    $ jruby -v
    jruby 1.3.1 (ruby 1.8.6p287) (2009-06-15 2fd6c3d) (Java HotSpot(TM) Client VM 1.5.0_16) [i386-java]
  7. Great. Now we’ll need to install Rails and some other gems.
    $ jruby -S gem install rails

    Once this is complete, You’ll need to install the correct database driver. Since we are going to be deploying in Tomcat, we can’t use the regular old rails drivers. We’ll need to use a Java-based database driver (JDBC). For this tutorial, we’ll use MySQL:
    $ jruby -S gem install activerecord-jdbcmysql-adapter

    While we’re installing gems, let’s grab openssl:
    $ jruby -S gem install jruby-openssl

    If you’re not using MySQL, you’ll be able to find other drivers here.

    And now the key to this whole thing… Warble. Warble is what takes a Rails app, and turns it into a .war file that can be dropped into most any Java container. We will install it on the JRuby side. Warble comes with an executable script called “warble” that will be available in your terminal. Install warbler by issuing:
    $ jruby -S gem install warbler

    Now we’ve got everything we need.
  8. Let’s create a simple phonebook application to test out our installation.
    $ jruby -S rails phonebook --database mysql

    Now, modify your database.yml file to look something like this:
      adapter: jdbcmysql
      encoding: utf8
      reconnect: false
      database: phonebook_development
      username: root
      host: localhost
      adapter: jdbcmysql
      encoding: utf8
      reconnect: false
      database: phonebook_test
      username: root
      host: localhost
      adapter: jdbcmysql
      encoding: utf8
      reconnect: false
      database: phonebook_production
      username: root
      host: localhost

    Notice that for the adapter, we’re using jdbcmysql. Make sure you also edit your credentials appropriately. Now, let’s create our databases. You should create the production database also, as Tomcat will run your app in the production environment by default:
    $ mysqladmin -u root create phonebook_development
    $ mysqladmin -u root create phonebook_production
  9. Now let’s create some scaffolding.
    $ jruby -S script/generate scaffold Person first_name:string last_name:string phone_number:string address:text

    …and let’s migrate the database:
    $ jruby -S rake db:migrate
    $ jruby -S rake db:migrate RAILS_ENV=production

    Alright. Let’s fire it up in WEBrick to test what we’ve got:
    $ jruby -S script/server

    Go ahead and check out http://localhost:3000/people. You should see your app running in JRuby. Awesome.
  10. Now let’s get it running in Tomcat.
    We’re going to use Warble to make our dreams come true. In your app directory issue this command:
    $ warble pluginize

    This gives us a bunch of rake commands that will might be useful in building your .war file. These are the rake see what commands are available, just issue this:
    $ warble -T
    rake config             # Generate a configuration file to customize your w...
    rake pluginize          # Unpack warbler as a plugin in your Rails application
    rake version            # Display version of warbler
    rake war                # Create phonebook.war
    rake war:app            # Copy all application files into the .war
    rake war:clean          # Clean up the .war file and the staging area
    rake war:exploded       # Create an exploded war in the app's public directory
    rake war:gems           # Unpack all gems into WEB-INF/gems
    rake war:jar            # Run the jar command to create the .war
    rake war:java_classes   # Copy java classes into the .war
    rake war:java_libs      # Copy all java libraries into the .war
    rake war:public         # Copy all public HTML files to the root of the .war
    rake war:war:java_libs  # Copy all java libraries into the .war
    rake war:webxml         # Generate a web.xml file for the webapp

    Now, we’re going to add a warble config file to our application by issuing this:
    $ warble config

    This will generate a file called warble.rb in the /config directory of your app. Go ahead and open that up. Uncomment the line that looks like this:
    config.gems += ["activerecord-jdbcmysql-adapter", "jruby-openssl"]

    This will make sure that the database driver and openssl gems are bundled in our .war file. Go ahead and list any gems that your app depends on here. Warble will include the Rails gems by default, so you don’t need to worry about those.

    Now you’re ready for the magic. Back in your terminal, issue:
    $ warble

    After some output, you’re app will appear bundled up in your app’s root directory. Also, note that in the tmp directory of your app, you’ll now see a war directory. If you want to build your .war file in the future from scratch, delete this directory, and issue the warble command again. Otherwise, when you run warble, it will only add files to the bundle that have been added or modified since the last execution of warble.

    Now drop the phonebook.war file into the webapps directory of your Tomcat installation.

  11. Deploy in Tomcat
    Make sure Tomcat is started. (see above)

    Point a browser to http://localhost:8080/phonebook. Congratulations! You’ve just deployed your first JRuby on Rails application in a Tomcat container.

Filed in ruby rails tomcat jruby tutorials programming

  1. thenice posted this