September 11th, 2007 by Lou
This post is a synthesis of information from several sources and provides step-by-step instructions for building and deploying a Ruby in Rails application to Glassfish that uses J2EE standard JDBC connection pooling mechanisms. This is the preferred method for production deployments to a J2EE server of any scale, since
- it leverages J2EE deployment mechanisms, fully separating operational and development roles (database passwords can be configured by operations using the same mechanisms used fro J2EE applications), and
- it utilizes the connection pooling mechanisms available in J2EE servers to reduce connection overhead for managing connections to the database server, increasing scalability and reducing CPU and memory utilization for this activity.
In other words, if you are currently using Mongrel in your deployments, and are considering a JRuby Rails deployment, this mechanism is for you.
These instructions should work with application server specific modifications for any J2EE compliant server are JRuby RoR capable, such as Web Logic 9.2 application servers. These instructions leverage NetBeans, but may choose to create the deployment war from the command line using the Goldspike plugin. (See Rails Integration on the JRuby Wiki.)
Resources Used for this Entry
- Arun Gupta on Glassfish and JRuby
- JRuby Wiki on JNDI Configuration of Web Servers
- Running Rails with ActiveRecord-JDBC
- An installation of a recent version of NetBeans and Glassfish per Arun’s instructions with a running JRuby on Rails application and MySQL backend. You can also use a pre-existing Ruby on Rails MySQL application. If it isn’t already a NetBeans project, you should create one, specifying project creation from existing sources, "Ruby on Rails with Existing Sources".
- The MySQL JDBC jar file for installation. The latest as of this writing is version 5.0.7. I used version 5.0.5. (mysql-connector-java-5.0.5-bin.jar). Note that you will have already deployed this same jar file in the $JRUBY_HOME/lib directory, if you have been doing JRuby Rails development.
- Note that Arun’s instructions are currently missing a step to update the
environment.rbfile, as specified in prior iterations of his instructions as well as elsewhere. (See Running Rails with ActiveRecord-JDBC step 9.) This is required for the JRuby JDBC connection architecture to function correctly. Also note that the only difference between these instructions and those is the use of the J2EE JDBC connection pooling mechanism, rather than a monolithic JDBC connection managed by the deployed JRuby RoR application. The simpler mechanism is fine for development environments and small deployments.
- Modify the war file xml to include a JNDI reference to a JDBC connection pool
- Modify the
database.ymlfile to use the JNDI reference
- Install the MySQL JDBC connector in the Glassfish lib directory
- Create a JDBC resource and connection pool in the Glassfish administrator console
- Create and deploy the application war file
Modify WAR File XML
Perform Step 3 from JRuby Wiki entry on Using a connection from a pool via JNDI on the
create_war.rb file in the Ruby on Rails project
./vendor/plugins/goldspike/lib/create_war.rb. This modifies the goldspike plugin to create a war file with the JNDI descriptor we need. Insert this snippet Replace the string
MyApp with a meaningful name for your database connection resource. My example below shows the snippet with my JNDI name "jdbc/roadmap".
Modify the database.yml File
In this step we modify
database.yml to refer to the JNDI name, rather than directly to the JDBC driver. No usernames, hostname or passwords are configured in the
database.yml after this step, completely decoupling these database configuration from the application. We are making these modifications to the
production connection specification, so you could continue to use your standard Rails database configuration with your local MySQL database development instance. The example below shows this.
Install the MySQL JDBC connector in the Glassfish lib directory
You should follow the standard instructions for installing and configuring Glassfish for your environment. I downloaded and installed Release Candidate 8. After this, install the MySQL connector jar in the Glassfish
lib directory. In my case, Glassfish is installed in my
/opt directory so I
cp mysql-connector-java-5.0.5-bin.jar /opt/glassfish/lib.
Create a JDBC Resource and Connection Pool in the Glassfish Administrator Console
Your Glassfish server should already be started. Refer to the Glassfish Quickstart for basic startup and shutdown instructions. Once the server is started, go to the URL for the administrators console, http://localhost:4848 if the installation is on your local machine. The default
password are "admin" and "adminadmin" respectively. Select "Resources", "JDBC", "Connection Pools" int he tree view on the left as shown below.
Connection properties are specified as "properties" in the "Additional Properties" panel toward the bottom of the page. We only need to configure a handful of these, the defaults are fine for the rest. These are based on your database hostname, MySQL connection port, username and password.
URLshould be something like "jdbc:mysql://localhost:3306/roadmap_development". Replace "localhost" with a hostname if your database is on a remote host. Replace "roadmap_development" with the name of your MySQL database. 3306 is the default TCP/IP port for MySQL.
Urlshould be the same as "URL". Note: I have no idea why both are properties. One will likely suffice.
Useris the database user for the database.
Passwordis the password.
Specify "jdbc/poolname" as the JNDI name, where "poolname" is a meaningful name for your resource, like you gave your connection pool in the previous step. My poolname was "roadmap". Select the pool name you created in the previous step for the Pool Name. Click OK.
Create and Deploy the Application WAR File
Create the application war file as specified in Arun’s instructions, right clicking ont he project in NetBeans and creating a standalone war file. This file is created int the project root directory. Copy this file to the autodeploy directory for the application server, in my case
/opt/glassfish/domains/domain1/autodeploy. The application should be deployed in a few seconds on the 8080 port of the server, something like "http://localhost:8080/roadmap", replacing "roadmap" with your Rails application name.