JBoss.orgCommunity Documentation

Chapter 5. Application Deployment

5.1. Rake tasks
5.1.1. Deploying a non-root context
5.1.2. Deploying to a non-development environment
5.2. Deploy using a descriptor
5.3. Deployment using a self-contained archive
5.3.1. Configuring an archive
5.3.2. Creating an archive
5.3.3. Deploying an archive

The TorqueBox Application Server is capable of serving many applications simultaneously. To add your application to the server, you must deploy it. To deploy an application, you put some artifact in the apps/ directory of the TorqueBox AS. When the AS is running, it will detect that artifact and activate the associated application.

TorqueBox includes a support package which includes Rake tasks which assist in the deployment to and undeployment from an instance of the TorqueBox Server.

First, the $TORQUEBOX_HOME and $JBOSS_HOME variables must be set to the path of the top of your TorqueBox Installation and the JBoss installation inside of it, respectively, as described in Chapter 2, Installation.

$ export TORQUEBOX_HOME=/path/to/torquebox
$ export JBOSS_HOME=$TORQUEBOX_HOME/jboss

If you're using any configuration other than default, you must also set $JBOSS_CONF.

$ export JBOSS_CONF=web

You need to include these tasks into your Rakefile using a single require statement.

require 'torquebox-rake-support'

Once these variables are set, you may perform a default deployment using the torquebox:deploy task to deploy either Ruby-on-Rails applications or plain Ruby Rack applications.

$ rake torquebox:deploy

To undeploy your application, the torquebox:undeploy task is available

$ rake torquebox:undeploy

The TorqueBox Server does not need to be running for these commands to work.

By default, these tasks deploy your application to root of your TorqueBox Server's web space, without any virtual host configuration. To access the application once deployed, you should use your browser to access http://localhost:8080/.

When the application is deployed, a deployment descriptor is written to the $TORQUEBOX_HOME/apps/ directory with a filename based upon the directory name of your current directory.

For instance, if your application was deployed from /Users/bob/myapp/, the deployment descriptor would be named myapp-knob.yml.

Rewriting or simply updating the last-modified time (using a command such as touch) of this descriptor will cause the TorqueBox server to redeploy the application. The torquebox:deploy task simply emits this file.

Removing the descriptor will cause the TorqueBox server to undeploy the application. This is what the torquebox:undeploy task does.

To customize some of the aspects of deployment, instead of using the Rake tasks, you may manually create a deployment descriptor.

A deployment descriptor is a small text file that is placed in the apps/ directory of the TorqueBox server. This directory is constantly monitored for changes. To deploy an app, add a descriptor with a suffix of -knob.yml. To redeploy or "bounce" the app, edit or touch the descriptor. To undeploy it, remove the descriptor. This is precisely what the torquebox:deploy and torquebox:undeploy rake tasks do.

For details on the various options for authoring deployment descriptors, see Chapter 6, Deployment Descriptors.

Ruby web applications may be deployed as atomic self-contained archives. An archive is simply a packaging of the application's directory. The TorqueBox server deploys bundles created with the Java jar tool. Rake tasks are provided to assist with the creation and deployment of bundles.

Typically, an application is configured using a deployment descriptor suffixed by -knob.yml and placed in $TORQUEBOX_HOME/apps/. We refer to this file as an external descriptor, because it resides outside of the app's root directory.

An application archive may be configured using an internal descriptor as well. This descriptor should be named torquebox.yml and contained within the archive's config/ directory for a Rails app or the root directory of a Rack app. This is described in more detail in Chapter 6, Deployment Descriptors.

When your application is packaged as a fully-described self-contained archive, you may override portions of the internal descriptor using an external descriptor. If you do, make sure that only the external descriptor resides beneath $TORQUEBOX_HOME/apps/. The archive containing the (possibly overridden) internal descriptors should reside elsewhere on the filesystem, its path referenced in the external descriptor. Having both the archive and the external descriptor beneath $TORQUEBOX_HOME/apps/ will result in errors stemming from two separate deployments of the same app.