IntroductionI 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.
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/
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
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
$ /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
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/
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
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]
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.
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
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.
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:
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.
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.