<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="torquebox-server-gem">
  <title>torquebox-server Gem</title>

  <para>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 <command>torquebox</command> command to
  deploy and undeploy applications and start Torquebox.</para>

  <section id="install-jruby">
    <title>Install JRuby</title>

    <para>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.</para>

    <para>Follow instructions at <ulink
    url="http://jruby.org">http://jruby.org</ulink> to install JRuby
    if it isn't already.</para>
  </section>

  <section id="installing-torquebox-server">
    <title>Install torquebox-server</title>

    <screen><prompt>$</prompt> <command>jruby -S gem install torquebox-server</command></screen>

    <para>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.</para>
  </section>

  <section id="applications-torquebox-server">
    <title>Deploying and Undeploying Applications</title>

    <para>The torquebox-server gem ships with a <command>torquebox</command>
      binary, which may be used to deploy and undeploy applications, as well
      as starting the server and other functions. For complete documentation,
      see <xref linkend="torquebox-cmd" />.</para>

    <para>To deploy an application to TorqueBox:

    <screen><prompt>$</prompt> <command>torquebox deploy /path/to/my_app</command></screen>

    To undeploy that same application:

    <screen><prompt>$</prompt> <command>torquebox undeploy /path/to/my_app</command></screen>

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

    <formalpara>
      <title>Deployment Help</title>

      <screen><prompt>$</prompt> <command>torquebox help deploy</command>
Usage:
  torquebox deploy ROOT

Options:
  [--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)

Description:
  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).</screen>
    </formalpara>

    <formalpara>
      <title>Undeployment Help</title>

      <screen><prompt>$</prompt> <command>torquebox help undeploy</command>
Usage:
  torquebox undeploy ROOT

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

Undeploy an application from TorqueBox</screen>
    </formalpara>
  </section>

  <section id="running-torquebox-server">
    <title>Running</title>

    <para>Running TorqueBox is as simple as:

    <screen><prompt>$</prompt> <command>torquebox run</command></screen>

    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:

    <screen><prompt>$</prompt> <command>torquebox run -b 10.100.10.25</command>
<prompt>$</prompt> <command>torquebox run -b 0.0.0.0</command></screen>

    To run TorqueBox in clustered mode, use:

    <screen><prompt>$</prompt> <command>torquebox run --clustered</command></screen>

    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.

    <screen><prompt>$</prompt> <command>torquebox run --clustered --node-name=node1 --data-directory=/tmp/node1 -b 10.100.10.25</command>
<prompt>$</prompt> <command>torquebox run --clustered --node-name=node2 --data-directory=/tmp/node2 -b 10.100.10.26</command></screen>

    <screen><prompt>$</prompt> <command>torquebox run --clustered --node-name=node1 --data-directory=/tmp/node1</command>
<prompt>$</prompt> <command>torquebox run --clustered --node-name=node2 --data-directory=/tmp/node2 --port-offset=100</command></screen>
    </para>

    <formalpara>
      <title>Run Help</title>

      <screen><prompt>$</prompt> <command>torquebox help run</command>
Usage:
  torquebox run

Options:
      [--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 0.0.0.0 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)</screen>
    </formalpara>
  </section>

  <section id="torquebox-server-environment">
    <title>Shortcuts For Accessing Paths Inside torquebox-server Gem</title>

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

    <screen><prompt>$</prompt> <command>torquebox env torquebox_home</command></screen>

    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.</para>

    <example>
      <title>Tailing AS7 boot.log File</title>

      <screen><prompt>$</prompt> <command>tail `torquebox env jboss_home`/standalone/log/boot.log</command>
11:26:32,107 INFO  [jacorb.poa] POA RootPOA destroyed
11:26:32,109 INFO  [jacorb.orb] prepare ORB for shutdown...
11:26:32,110 INFO  [jacorb.orb] ORB going down...
11:26:32,112 INFO  [jacorb.orb] ORB shutdown complete
11:26:32,113 INFO  [jacorb.orb.iiop] Listener exited
11:26:32,113 INFO  [jacorb.orb] ORB run, exit
11:26:32,143 INFO  [org.hornetq.core.server.impl.HornetQServerImpl] HornetQ Server version 2.2.7.Final (HQ_2_2_7_FINAL_AS7, 121) [612e2de5-f41d-11e0-b7b8-005056c00008] stopped
11:26:33,782 WARN  [org.torquebox.core.runtime] No initializer set for runtime
11:26:33,801 INFO  [org.torquebox.core.runtime] Created ruby runtime (ruby_version: RUBY1_8, compile_mode: JIT, context: global) in 9.86s
11:26:33,806 INFO  [org.jboss.as] JBoss AS 7.0.2.Final "Arc" stopped in 1729ms</screen>
    </example>
  </section>
</chapter>
