<?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="installation">
  <title>TorqueBox Installation</title>

  <section id="using-rubygems">
    <title>Installation using RubyGems</title>

    <para>TorqueBox 2 can be installed entirely as a RubyGem. For
    details, please see <xref linkend="torquebox-server-gem"/>.
    TorqueBox can also be installed from a binary distribution
    as described below.</para>
  </section>

  <section id="using-complete-binary">
    <title>Installation using Complete Binary Distribution</title>

    <para>The latest Complete Binary Distribution contains:</para>

    <itemizedlist spacing="compact">
      <listitem>
        <para>The TorqueBox server, ready-to-run</para>
      </listitem>

      <listitem>
        <para>A complete JRuby installation</para>
      </listitem>

      <listitem>
        <para>Additional RubyGems for use in other contexts</para>
      </listitem>
    </itemizedlist>

    <para>Note: these instructions assume you are running on a unix-like system.
    If you are using Windows, you will need to adjust the file-system paths and
    environment variables accordingly.</para>

    <section id="ensure-you-have-java6">
      <title>Ensure you have Java 6</title>

      <para>TorqueBox requires Java JDK 6.</para>

      <para>To determine which version, if any, is installed on your system, at
      a command-line, attempt to run the <command>java</command> command with
      the <option>-version</option> argument.</para>

      <screen><prompt>$</prompt> <command>java -version</command>
java version "1.6.0_07"
Java(TM) SE Runtime Environment (build 1.6.0_07-b06-153)
Java HotSpot(TM) 64-Bit Server VM (build 1.6.0_07-b06-57, mixed mode)</screen>

      <para>If the version is at least 1.6, your version of Java is
      sufficient.</para>

      <para>If you have no Java installed, or a version less than 1.6, you'll
      need to install a Java Development Kit. For many systems, it is easy to
      install the open-source OpenJDK.</para>

      <para>For installation on Ubuntu, Fedora, OpenSuse, or Debian, please
      refer to the <ulink url="http://openjdk.java.net/install/">installation
      instructions provided</ulink> by the OpenJDK project. If you find a
      <command>java</command> on your system, ensure that it is not actually
      <command>gcj</command>, as it is insufficient for
      running the TorqueBox server.</para>

      <para>For Apple OSX systems, Apple provides a JDK version 6.</para>
    </section>

    <section id="get-latest-torquebox-binary-package">
      <title>Get the latest version of TorqueBox binary package</title>

      <para>You can obtain the latest version of TorqueBox from the TorqueBox
      repository. As of this writing, the latest version is
      ${project.version}.</para>

      <para><ulink
    url="http://repository-projectodd.forge.cloudbees.com/release/org/torquebox/torquebox-dist/${project.version}/torquebox-dist-${project.version}-bin.zip">http://repository-projectodd.forge.cloudbees.com/release/org/torquebox/torquebox-dist/${project.version}/torquebox-dist-${project.version}-bin.zip</ulink></para>
    </section>

    <section id="unzip-the-package">
      <title>Unzip it somewhere handy</title>

      <para>We'll install TorqueBox under your user's <envar>$HOME</envar> directory.</para>

      <para><screen><prompt>$</prompt> <command>unzip -q torquebox-dist-${project.version}-bin.zip</command>
      </screen></para>

      <para>Before using the TorqueBox server, you must set up your environment.
      To make it easier to upgrade without having to reconfigure your
      environment, it is useful to create a symlink to the versioned directory
      produced when you unpackaged the distribution.</para>

      <para><screen><prompt>$</prompt> <command>ln -s torquebox-${project.version} torquebox-current</command></screen></para>

      <para>Next, <envar>$TORQUEBOX_HOME</envar>, <envar>$JBOSS_HOME</envar> and
      <envar>$JRUBY_HOME</envar> need to be set, and adjusting your
      <envar>$PATH</envar> will make working with the package easier. You can
      either run the following commands each time on the command-line, or add
      them to your <filename>.bash_profile</filename>.</para>

      <para>First, the various <envar>$<replaceable>X</replaceable>_HOME</envar>
      variables are set so that each subsystem can find its supporting
      files.</para>

      <para><screen>export TORQUEBOX_HOME=$HOME/torquebox-current
export JBOSS_HOME=$TORQUEBOX_HOME/jboss
export JRUBY_HOME=$TORQUEBOX_HOME/jruby</screen></para>

      <para>Next, we make sure that JRuby's binaries are first in our executable
      <envar>$PATH</envar>, before any previously-installed Ruby
      packages.</para>

      <para><screen>export PATH=$JRUBY_HOME/bin:$PATH</screen>By doing
      this, commands such as <command>rake</command>, <command>gem</command>,
      and <command>rails</command> will load from the TorqueBox-provided JRuby
      installation.</para>

      <para>You can also run TorqueBox using your own install of
      JRuby by installing the TorqueBox gems.

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

      You will also need to set <envar>$JRUBY_HOME</envar> to point to
      your JRuby installation.</para>

      <para><emphasis>Note:</emphasis> if you are going to run a non-bundled JRuby
      with a prerelease build of TorqueBox, it is recommended that you either use a
      separate <ulink url="http://rvm.beginrescueend.com">rvm</ulink> <ulink
      url="http://rvm.beginrescueend.com/gemsets/">gemset</ulink> for each prerelease
      build, or be sure to reinstall the TorqueBox gems for the latest prerelease.
      There is a <ulink url="http://torquebox.org/news/2011/12/19/using-rvm-with-torquebox/">blog post</ulink> 
      on torquebox.org describing how to 
      set up your torquebox environment with RVM.</para>

      <para>For prerelease builds, you will also need to ensure that
      your <command>gem</command> command can find the prerelease
      TorqueBox gems by adding http://torquebox.org/2x/builds/LATEST/gem-repo/
      to your <filename>~/.gemrc</filename> file and including the
      <command>--pre</command> flag to <command>gem install</command>. 
        <screen>
<prompt>$</prompt> <command>cat ~/.gemrc</command>
--- 
:sources: 
- http://rubygems.org
- http://torquebox.org/2x/builds/LATEST/gem-repo/</screen>
      </para>
    </section>
    <section>
      <title>Configuring Your Database</title>
      <para>
        TorqueBox includes distributed (XA) transaction support by default. In order to take advantage
        of XA, you may need to alter your database configuration. See <xref linkend="transaction-configuration" /> 
        for details.
      </para>
    </section>

    <section id="running-torquebox">
      <title>How to run TorqueBox</title>

      <para>Running TorqueBox essentially amounts to running JBoss:</para>
    
      <screen><prompt>$</prompt> <command>$JBOSS_HOME/bin/standalone.sh</command></screen>

      <para>TorqueBox also ships rake tasks and the torquebox binary, both of which can
      be used to start the server. See <xref linkend="rake-server-control"/> and <xref 
      linkend="torquebox-cmd-run"/> for more details.</para>
    </section>
  </section>

  <section id="setting-jvm-properties">
    <title>Setting JVM Properties</title>

    <para>If using the <command>torquebox</command> command (<xref
    linkend="torquebox-cmd"/>), JVM properties can be set with the -J
    flag. The only caveat is hypens must be escaped with a "\".
    </para>

    <para>For example:
      <informalexample>
        <para><screen><prompt>$</prompt> <command>torquebox run -J "\-Xmx2048m \-Djruby.jit.logging=true"</command></screen></para>
      </informalexample>
    </para>

    <para>If using <command>standalone.sh</command>, just append the
    JVM properties to the end of the command.</para>

    <para>For example:
      <informalexample>
        <para><screen><prompt>$</prompt> <command>$JBOSS_HOME/bin/standalone.sh -Djruby.jit.logging=true</command></screen></para>
      </informalexample>
    </para>

    <para>If you'd prefer not to pass the JVM properties on the
    commandline, they can also be set in
    <filename>$JBOSS_HOME/bin/standalone.conf</filename> by appending
    to the <varname>JAVA_OPTS</varname> variable.</para>

    <para>For example:
      <informalexample>
        <para><programlisting>...
if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS="-Xms64m -Xmx512m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000"
   JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"
   JAVA_OPTS="$JAVA_OPTS -Djboss.server.default.config=standalone.xml"
else
   echo "JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS"
fi

JAVA_OPTS="$JAVA_OPTS -Djruby.jit.logging=true"</programlisting></para>
      </informalexample>
    </para>

    <para>You can also set the JAVA_OPTS environment variable directly
    in the shell, but if you do this make sure you copy the increased
    MaxPermSize from
    <filename>$JBOSS_HOME/bin/standalone.conf</filename> since if
    JAVA_OPTS is set in the shell the defaults in this file won't be
    applied.</para>

    <para>For example:
      <informalexample>
        <para><screen><prompt>$</prompt> <command>export JAVA_OPTS="-Xmx1024m -XX:MaxPermSize=256m -Djruby.jit.logging=true"</command></screen></para>
      </informalexample>
    </para>

  </section>

  <section id="setting-jruby-properties">
    <title>Setting JRuby Properties</title>

    <para>While some JRuby properties can be set via torquebox.yml or
    torquebox.rb as shown in <xref
    linkend="ruby-runtime-config-in-descriptor"/>, JRuby supports many
    more options than the ones TorqueBox exposes directly. As long as
    you are using the <command>torquebox</command> command (<xref
    linkend="torquebox-cmd"/>), you can set these other properties
    with the <varname>JRUBY_OPTS</varname> environment
    variable.</para>

    <para>For example:
      <informalexample>
        <para><screen><prompt>$</prompt> <command>export JRUBY_OPTS="-X+C --1.9 -Xjit.logging=true"</command>
<prompt>$</prompt> <command>torquebox run</command></screen></para>
      </informalexample>
    </para>

    <para>If you are not using the <command>torquebox</command>
    command, <varname>JRUBY_OPTS</varname> can still be used for
    options like "--1.9", "--1.8", "-X+C", "+X-O", but not for options
    of the style "-Xa.b" like "-Xjit.logging=true". The latter options
    will need to be set as JVM properties (<xref
    linkend="setting-jvm-properties"/>) by prefixing them with
    "jruby." like "-Djruby.jit.logging=true".</para>

    <para>For example:
      <informalexample>
        <para><screen><prompt>$</prompt> <command>export JRUBY_OPTS="-X+C --1.9"</command>
<prompt>$</prompt> <command>$JBOSS_HOME/bin/standalone.sh -Djruby.jit.logging=true</command></screen></para>
      </informalexample>
    </para>
  </section>
</chapter>
