Chapter 5. TorqueBox Deployment Descriptors

TorqueBox applications contain one central but optional internal deployment descriptor. A deployment descriptor is simply a configuration file that affects how your components are woven together at deployment time. The internal deployment descriptor used by TorqueBox can be either a YAML text file (known as torquebox.yml) or a Ruby file (known as torquebox.rb).

The deployment descriptor may be placed inside your application so that it is entirely self-contained. Alternatively, an additional (YAML only) external descriptor may be used outside of your application, overriding portions of the descriptor contained within the application.

Each subsystem within TorqueBox may contribute one or more configurable sections to the descriptor. For more information on the various subsystem descriptor sections, please see: Chapter 6, TorqueBox Web Applications, Chapter 8, TorqueBox Messaging, Chapter 9, STOMP & WebSockets on TorqueBox, Chapter 10, TorqueBox Scheduled Jobs, Chapter 11, TorqueBox Services, Chapter 13, TorqueBox Authentication, and Chapter 16, TorqueBox Runtime Pooling.

5.1. External and Internal descriptors

Deployment descriptors may be "external", residing outside the application, or "internal", residing within it. The descriptors come in two flavors: YAML-formatted text files and Ruby text files using the TorqueBox configuration DSL. Internal descriptors may use either form, but external descriptors are required to be YAML files.

An external descriptor references an application somewhere on your filesystem. To deploy the application, the descriptor is placed in the $TORQUEBOX_HOME/jboss/standalone/deployments/ directory of the TorqueBox server. The external descriptor's name should have a suffix of -knob.yml .

An internal descriptor should be named torquebox.yml or torquebox.rb and reside inside the application's config/ directory, if present, otherwise at the root. Internal descriptors allow you to override the TorqueBox defaults but only for a single app. As such, they are not required. Values in the external descriptor override those in the internal descriptor which, in turn, override the TorqueBox defaults. The YAML syntax used in the external descriptor is identical to the syntax available to the internal descriptor.

5.2. Contents of a descriptor

There are two syntaxes available for use in an internal descriptor: YAML and a Ruby DSL. For the configuration specifics for each subystem, see: Chapter 6, TorqueBox Web Applications, Chapter 8, TorqueBox Messaging, Chapter 9, STOMP & WebSockets on TorqueBox, Chapter 10, TorqueBox Scheduled Jobs, Chapter 11, TorqueBox Services, Chapter 13, TorqueBox Authentication, and Chapter 16, TorqueBox Runtime Pooling.

5.2.1. YAML syntax layout

The YAML descriptor has several sections, grouped by subsystem, represented as top-level keys in a YAML associative array.

5.2.2. Ruby DSL syntax layout

The DSL does not follow the strict sections of the YAML syntax, but the corresponding DSL methods can be grouped and described in the same manner.

To use the DSL, you nest your configuration inside the block passed to TorqueBox.configure inside torquebox.rb:

TorqueBox.configure do
  # DSL calls go here
end

The TorqueBox.configure method and the DSL methods that take a block can be given a block with or without an argument. If given a block argument, the block will receive a proxy object that must be used to call the DSL methods. Without an argument, the block will use instance_eval to evaluate the DSL calls, which will cause issues if you refer to any variables that aren't defined within the scope of the block. Most of the documentation examples use the instance_eval (no argument) block syntax.

Using no-argument blocks:

TorqueBox.configure do
  web do
    context "/"
  end
end

Using argument blocks:

TorqueBox.configure do |cfg|
  cfg.web do |web|
    web.context "/"
  end
end

You can also mix & match:

TorqueBox.configure do
  web do |web|
    web.context "/"
  end

  ruby do
    version "1.9"
  end
end

Some DSL methods can also take their options as a hash instead of method calls nested in a block:

TorqueBox.configure do
  web :context => "/", :host => "example.com"

  # is equivalent to:

  web do
    context "/"
    host "example.com"
  end
end

5.2.3. General Application Configuration

Location

The application section describes the location for the app itself. Under traditional (mongrel, lighttpd) deployments, this information is picked up through the current working directory. Since the TorqueBox Server runs from a different location, the current working directory has no meaning.

Table 5.1. application

YAML Key	DSL Method	Description	Default
`root`	none	Indicates the location of your application. It may refer to either an "exploded" application (a directory) or the path to a zipped archive. It is required for external descriptors and ignored in an internal descriptor. Rails apps will have this value set as ENV['RAILS_ROOT'], and Rack apps will have this value set to both the RACK_ROOT constant and ENV['RACK_ROOT'].	none

For example, in YAML:

application:
  root: /path/to/myapp

5.2.4. Ruby runtime configuration

TorqueBox exposes several of the JRuby runtime options: the ruby compatibility version, the JIT compile mode, and the debug setting. There's also a setting to enable interactive tty for the JRuby runtime for use with the Ruby debugger. All of these options are configured in the ruby: section of a deployment descriptor.

Note that these settings are per application, allowing you to run 1.8 and 1.9 applications in the same TorqueBox, or have one JIT'ed and another not.

In a YAML configuration, the ruby settings are grouped under the ruby key. For the DSL, they are grouped within the ruby block.

Table 5.2. ruby

YAML Key/DSL Method	Description	Default
`version`	The ruby compatibility version for JRuby. Options are: 1.8 - provides 1.8.7 compatibility 1.9 - provides 1.9.2 compatibility	1.8
`compile_mode`	The JIT compile mode for JRuby. Options are: jit - Tells JRuby to use JIT on code where it determines there will be a speed improvement force - Tells JRuby to use JIT on all code off - Turns off JIT completely	`jit`
`debug`	A value of true enables JRuby's debug logging.	`false`
`interactive`	A value of true sets up the stdin/stdout/stderr of the JRuby runtime for interactive use instead of being redirected to the logging subsystem. Enable this when using the Ruby debugger or the pry gem.	`false`
`profile_api`	A value of true enables JRuby's profiler instrumentation, which allows you to obtain performance information on a given block of ruby code. For more information, check out How to Use the New JRuby Profiler	`false`

For example, in YAML:

ruby:
  version: 1.9
  compile_mode: off
  debug: false
  interactive: true
  profile_api: true

And via the DSL:

TorqueBox.configure do
  ruby do
    version "1.9"
    compile_mode "off"
    debug false
    interactive true
    profile_api true
  end
end

5.2.5. Environment variables

Each application may have its own unique set of environment variables, no matter how many different apps are deployed under a single TorqueBox instance. Variables from internal and external descriptors are merged, with the external variables overriding any internal matching keys.

In a YAML configuration, the environment settings are grouped under the environment key. For the DSL, they are grouped within the environment block.

For example, in YAML:

environment:
  MAIL_HOST: mail.yourhost.com
  REPLY_TO: you@yourhost.com

And via the DSL:

TorqueBox.configure do 
  environment do
    MAIL_HOST 'mail.yourhost.com'
    REPLY_TO 'you@yourhost.com'
  end
end

Any variable set in the environment section is accessible from within the application using the ENV hash, e.g. ENV['MAIL_HOST']=='mail.yourhost.com'

5.2.5.1. Application environment

To set the environment for the application, set either RACK_ENV or RAILS_ENV as an environment variable. They are equivalent, and will both work for a Rack or Rails application. If the application environment is not set, it will default to 'development'. Rails apps will have this value set as ENV['RAILS_ENV'] (which Rails itself will assign to Rails.env), and Rack apps will have this value set to both the RACK_ENV constant and ENV['RACK_ENV'].

For example, in YAML:

environment:
  RAILS_ENV: production

And via the DSL:

TorqueBox.configure do 
  environment do
    RAILS_ENV 'production'
  end
end

5.3. Java Deployment Descriptors

In addition to Ruby, Rails and TorqueBox-specific descriptors, your application may also include any traditional JavaEE or JBoss-specific descriptors within its config/ directory.