Inchoate Curmudgeon

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

Prerequisites

• 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.rb file, 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.

Summary Steps

• Modify the war file xml to include a JNDI reference to a JDBC connection pool
• Modify the database.yml file 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 userid and password are "admin" and "adminadmin" respectively. Select "Resources", "JDBC", "Connection Pools" int he tree view on the left as shown below.

Create a new connection pool with a Name of your choice and a "javax.sql.DataSource" connection type and "MySQL" Database Vendor as shown below. Press "Next" to continue.

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.

• URL should 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.
• Url should be the same as "URL". Note: I have no idea why both are properties. One will likely suffice.
• User is the database user for the database.
• Password is the password.

Press "Finish" to create the pool.

Next we need to create a JDBC Resource that  refers to this pool. Select JDBC Resources in the tree view on the left and click "New…" in the panel on the right.

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.

Trackback URI | Comments RSS