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

http://thenice.tumblr.com/post/133345213/deploying-a-rails-application-in-tomcat-with-jruby-a

 

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

Introduction

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 ./startup.sh
   
   

   This will start Tomcat as a daemon. You should see something like this:

   
   $ /apache-tomcat-5.5.27/bin: sudo ./startup.sh
   Password:
   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:

   
   development:
     adapter: jdbcmysql
     encoding: utf8
     reconnect: false
     database: phonebook_development
     username: root
     password:
     host: localhost
   test:
     adapter: jdbcmysql
     encoding: utf8
     reconnect: false
     database: phonebook_test
     username: root
     password:
     host: localhost
   production:
     adapter: jdbcmysql
     encoding: utf8
     reconnect: false
     database: phonebook_production
     username: root
     password:
     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.