<?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>
</chapter>
