JBoss.orgCommunity Documentation

Chapter 20. torquebox-server Gem

20.1. Install JRuby
20.2. Install torquebox-server
20.3. Deploying and Undeploying Applications
20.4. Running
20.5. Shortcuts For Accessing Paths Inside torquebox-server Gem

One of the new features is the ability to install TorqueBox as a gem instead of the zip-based installation. The gem installation gives you access to a new torquebox command to deploy and undeploy applications and start Torquebox.

Before installing the torquebox-server gem you'll want the latest JRuby installed. We recommend at least 1.6.7 since it fixes an out of memory error during gem install.

Follow instructions at http://jruby.org to install JRuby if it isn't already.

$ jruby -S gem install torquebox-server

If you're using a JRuby version older than 1.6.7, be you'll also need to pass "-J-Xmx1024m" to the jruby command above.

The torquebox-server gem ships with a torquebox binary, which may be used to deploy and undeploy applications, as well as starting the server and other functions. For complete documentation, see Chapter 17, The torquebox Command.

To deploy an application to TorqueBox:

$ torquebox deploy /path/to/my_app

To undeploy that same application:

$ torquebox undeploy /path/to/my_app

If you omit a path, the commands default to deploying or undeploying the application in the current directory.

Deployment Help
$ torquebox help deploy
  torquebox deploy ROOT

  [--context-path=CONTEXT_PATH]  # Context Path (ex: /, /my_app)
  [--env=ENV]                    # Application Environment (ex: development, test, production)
  [--name=NAME]                  # The desired name of the deployment artifact (ex: foo)

  Deploy an application to TorqueBox. The ROOT argument should point to either a 
  directory containing the application you want to deploy, a -knob.yml file, a 
  .knob archive, or any Java deployable artifact (.war, .ear, etc).
Undeployment Help
$ torquebox help undeploy
  torquebox undeploy ROOT

  [--name=NAME]  # The name of the artifact to undeploy (ex: foo)

Undeploy an application from TorqueBox

Running TorqueBox is as simple as:

$ torquebox run

Out of the box, TorqueBox only is only accessible from localhost. To access it from other machines pass the -b parameter to bind to a real IP address or any available IP address:

$ torquebox run -b
$ torquebox run -b

To run TorqueBox in clustered mode, use:

$ torquebox run --clustered

Multiple instances of TorqueBox can run on the same machine. You'll need to pass a unique node name, data directory, and bind each instance to a different IP address or use port offsets. Below are examples of setting up a local two-node cluster using different IP addresses and port offsets, respectively.

$ torquebox run --clustered --node-name=node1 --data-directory=/tmp/node1 -b
$ torquebox run --clustered --node-name=node2 --data-directory=/tmp/node2 -b

$ torquebox run --clustered --node-name=node1 --data-directory=/tmp/node1
$ torquebox run --clustered --node-name=node2 --data-directory=/tmp/node2 --port-offset=100

Run Help
$ torquebox help run
  torquebox run

      [--clustered]                      # Run TorqueBox in clustered mode
      [--data-directory=DATA-DIRECTORY]  # Override the directory TorqueBox uses to store it runtime data
  -e, [--extra=EXTRA]                    # Extra options to pass through to JBoss AS, you will to escape dashes with \ (e.g. \--help)
      [--max-threads=N]                  # Maximum number of HTTP threads
  -b, [--bind-address=BIND-ADDRESS]      # IP address to bind to - don't set this to if used with --clustered
      [--node-name=NODE-NAME]            # Override the name of the node (which by default is the hostname)
      [--port-offset=N]                  # Offset all port numbers listened on by TorqueBox by this number
  -J, [--jvm-options=JVM-OPTIONS]        # Pass options on to the JVM

Run TorqueBox (binds to localhost, use -b to override)

With our zip distribution, you set $TORQUEBOX_HOME, $JBOSS_HOME, and $JRUBY_HOME. These aren't set when installing TorqueBox as a gem but we provide an easy way to access those same paths if needed:

$ torquebox env torquebox_home

The available environment variables are torquebox_home, jboss_home, and jruby_home. Note that they are case-insensitive so you can use TORQUEBOX_HOME if you prefer.