<?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="rake-support">
  <title>TorqueBox Rake Support</title>

  <section id="deploy-using-rake" revision="1">
    <title id="rake-tasks">Overview</title>

    <para>TorqueBox includes a support package which includes Rake tasks which
    assist in the deployment to and undeployment from an instance of the
    TorqueBox Server, in addition to the launching of the server. This
    rake-based support is normally intended for development-time usage, and
    not for production. More advanced tooling, such as Capistrano (see
    Capistrano Support) is advisable for production environments.</para>

    <para>First, the <envar>$TORQUEBOX_HOME</envar> and
    <envar>$JBOSS_HOME</envar> variables must be set to the path of the top of
    your TorqueBox Installation and the JBoss installation inside of it,
    respectively, as described in <xref linkend="installation" />.</para>

    <para><informalexample>
        <screen><prompt>$</prompt> <command>export TORQUEBOX_HOME=/path/to/torquebox</command>
<prompt>$</prompt> <command>export JBOSS_HOME=$TORQUEBOX_HOME/jboss</command></screen>
      </informalexample></para>

    <para>To include these tasks into your <filename>Rakefile</filename>, use
    a <methodname>single</methodname> require statement.</para>

    <para><informalexample>
        <programlisting>require 'torquebox-rake-support'</programlisting>
      </informalexample></para>

    <para>Once these variables are set and you have adjusted your Rakefile,
    you may perform directory- or archive-based deployments and control the
    execution of the TorqueBox AS.</para>
  </section>

  <section>
    <title>Deploying applications</title>

    <section>
      <title>Directory-based deployments</title>

      <para>The typical usage of the rake tasks is to perform a deployment of
      your current application into a local TorqueBox AS during development.
      The simplest deployment form will deploy the application with
      <varname>RACK_ENV</varname> or <varname>RAILS_ENV</varname> set to
      <code>development</code>, no virtual host, at the root of the
      server.</para>

      <para><informalexample>
          <screen><prompt>$</prompt> <command>rake torquebox:deploy</command></screen>
        </informalexample></para>

      <para>If you wish to deploy with a different value for RACK_ENV or
      RAIL_ENV, the task respects your current shell's values for those
      variables.</para>

      <para><informalexample>
          <screen><prompt>$</prompt> <command>RAILS_ENV=staging rake torquebox:deploy</command></screen>
        </informalexample></para>
        
      <para>You may supply a name argument, either as a rake parameter or as an environment variable,
      to adjust the name of your -knob.yml file. If not supplied, the name of the deployment defaults 
      to the current directory name.</para>
      
      <para><informalexample>
        <screen><prompt>$</prompt> <command>rake torquebox:deploy['/my-app','foo']</command></screen>
        <screen><prompt>$</prompt> <command>rake torquebox:deploy NAME=foo</command></screen>
      </informalexample></para>
      
      <para>For example, running "rake torquebox:deploy NAME=foo" will create a deployment artifact
      called "foo-knob.yml" and deploy it accordingly.</para>

      <para>Additionally, a custom context path may be used instead of the
      default to of <code>/</code>, by providing a rake argument to the
      <command>torquebox:deploy</command> task.</para>

      <para><informalexample>
          <screen><prompt>$</prompt> <command>rake torquebox:deploy['/my-app']</command></screen>
        </informalexample></para>
    </section>

    <section id="rake-archive">
      <title>Archive-based deployments</title>

      <para>In the event you need to deploy the application as an archive,
      instead of as a directory of loose files, the rake support includes a
      task to do just that. Additional, the rake task may also be used to
      simply create the archive without deploying it, if you intend to
      distribute it to your servers in some other fashion.</para>

      <para>To create (but not deploy) an archive:</para>

      <para><informalexample>
          <screen><prompt>$</prompt> <command>rake</command> <command>torquebox:archive</command></screen>
        </informalexample></para>
        
      <para>Additionally, you can specify a name for the archive, either on the command line or as an 
      environment variable. For example, either of these statements:</para>
      <para><informalexample>
          <screen><prompt>$</prompt> <command>rake</command> <command>torquebox:archive[baz]</command></screen>
          <screen><prompt>$</prompt> <command>rake</command> <command>torquebox:archive NAME=baz</command></screen>
      </informalexample></para>     
      
      <para>will produce an archive called "baz.knob".</para>

      <para>The resulting archive will be placed at the root of the
      application, with a suffix of <filename>.knob</filename>. To inspect the
      contents, you may use the <command>jar</command> tool.</para>

      <para><informalexample>
          <screen><prompt>$</prompt> <command>jar</command> <option>tf</option> <filename><replaceable>myapp</replaceable>.knob</filename>
META-INF/
META-INF/MANIFEST.MF
app/
app/controllers/
app/controllers/application_controller.rb
...</screen>
        </informalexample></para>

      <para>You may also have the archive deployed immediately after creating
      it, in a single command. Here, as before, you may specify a name for the archive.</para>

      <para><informalexample>
          <screen><prompt>$</prompt> <command>rake</command> <command>torquebox:deploy:archive</command></screen>
          <screen><prompt>$</prompt> <command>rake</command> <command>torquebox:deploy:archive[baz]</command></screen>
          <screen><prompt>$</prompt> <command>rake</command> <command>torquebox:deploy:archive NAME=baz</command></screen>
        </informalexample></para>
    </section>
  </section>

  <section>
    <title>Undeploying applications</title>

    <para>To undeploy an application, either a directory- or archive-based
    deployment, a single command may be used:</para>

    <para><informalexample>
        <screen><prompt>$</prompt> <command>rake</command> <command>torquebox:undeploy</command></screen>
      </informalexample></para>
      
    <para>...but we also support torquebox:undeploy:archive for symmetry's sake:</para>
    <para><informalexample>
        <screen><prompt>$</prompt> <command>rake</command> <command>torquebox:undeploy:archive</command></screen>
        <screen><prompt>$</prompt> <command>rake</command> <command>torquebox:undeploy:archive[baz]</command></screen>
        <screen><prompt>$</prompt> <command>rake</command> <command>torquebox:undeploy:archive NAME=baz</command></screen>
      </informalexample></para>    
  </section>

  <section id="rake-server-control">
    <title>Server control</title>

      <para>TorqueBox provides rake tasks for controlling the server.</para>

      <screen><prompt>$</prompt> <command>cd $TORQUEBOX_HOME; jruby -S rake -T</command>
(in /opt/torquebox)
rake torquebox:check            # Check your installation of the TorqueBox ...
rake torquebox:run              # Run TorqueBox server
rake torquebox:upstart:check    # Check if TorqueBox is installed as an ups...
rake torquebox:upstart:install  # Install TorqueBox as an upstart service
rake torquebox:upstart:restart  # Restart TorqueBox when running as an upst...
rake torquebox:upstart:start    # Start TorqueBox when running as an upstar...
rake torquebox:upstart:stop     # Stop TorqueBox when running as an upstart...
      </screen>

      <itemizedlist>
        <listitem><command>torquebox:check</command>: Check your TorqueBox installation</listitem>
        <listitem><command>torquebox:run</command>: Run TorqueBox
        <para>The server will retain control of the console while it is running.
        To stop the server, simply send a <code>SIGINT</code>, typically by
        typing <keycap>control-C</keycap>.</para></listitem>
        <listitem><command>torquebox:upstart:check</command>: Check if TorqueBox is installed as an upstart service</listitem>
        <listitem><command>torquebox:upstart:install</command>: Install TorqueBox as an upstart service</listitem>
        <listitem><command>torquebox:upstart:restart</command>: Restart TorqueBox when it is running as an upstart service</listitem>
        <listitem><command>torquebox:upstart:start</command>: Start TorqueBox when it is installed as an upstart service</listitem>
        <listitem><command>torquebox:upstart:stop</command>: Stop TorqueBox when it is installed as an upstart service</listitem>
      </itemizedlist>

      <para>
        Note: The <command>upstart:install</command> task makes a couple of assumptions you need to take into account. 
        <itemizedlist>
          <listitem>You must have a 'torquebox' user on your system.</listitem>
          <listitem>The rake task attempts to create a symlink from $TORQUEBOX_HOME to /opt/torquebox. Run the task as a user with sufficient permissions so that this does not fail.</listitem>
      </itemizedlist>
      </para>
  </section>
</chapter>
