JBoss.orgCommunity Documentation

Chapter 5. TorqueBox Deployment Descriptors

5.1. External and Internal descriptors
5.2. Contents of a descriptor
5.2.1. YAML syntax layout
5.2.2. Ruby DSL syntax layout
5.2.3. General Application Configuration
5.2.4. Ruby runtime configuration
5.2.5. Environment variables
5.3. Java Deployment Descriptors
5.3.1. WEB-INF/web.xml

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.

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.

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.

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, 1.9, and 2.0 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.


For example, in YAML:

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

And via the DSL:

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