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

  <section id="what-is-capistrano">
    <title id="capistrano-support.title">What is Capistrano?</title>

    <para>Capistrano is a deployment tool to assist in moving code from a
    repository to a production server. It's a set of tools used from one
    machine (the deployer), to get an application running on a remote machine
    (the server).</para>

    <para>In many cases, the deployer is a developer working from his or her
    laptop. Capistrano is installed here. The deployer invokes the tooling
    locally on his laptop, and Capistrano reaches across the network to set up
    the right version of the application and activate it within
    TorqueBox.</para>
  </section>

  <section id="installing-capistrano">
    <title>Installing Capistrano</title>

    <para>The TorqueBox distribution includes support for Capistrano, but does
    not include Capistrano itself. Capistrano requires a few other gems in
    order to function effectively. It is easy to install everything.</para>

    <para><screen><prompt>$</prompt> <command>jruby</command> <option>-S</option> <command>gem</command> <command>install</command> jruby-openssl ffi-ncurses capistrano</screen></para>
  </section>

  <section id="capify-your-application">
    <title>Capify your Application</title>

    <para>You can skip this section if you're already using Capistrano with
    your application. Otherwise, you'll need to <command>capify</command> your
    application to set it up for use with Capistrano.</para>

    <para>Ensure that you are in the root of your application's source tree,
    and run the <command>capify</command> command.</para>

    <para><screen><prompt>$</prompt> <command>jruby</command> <option>-S</option> <command>capify</command> <filename>.</filename></screen>This
    creates a Capfile in the root of your application, which delegates to
    another file it created: <filename>config/deploy.rb</filename>. The
    deploy.rb file is the primary location for configuring your deployment
    strategy.</para>
    
    <section id="basic-deploy-rb-configuration">
      <title>Basic deploy.rb configuration</title>

      <para>All applications, whether using TorqueBox or another server,
      require some common settings to be used with Capistrano. The default
      <filename>deploy.rb</filename> indicates some typical variables you
      should customize for your deployment.</para>
    </section>
  </section>

  <section id="deploy-rb-configuration">
    <title>TorqueBox-specific deploy.rb configuration</title>

    <para>Within your <filename>deploy.rb</filename>, there are a few
    additional steps and variables you may configure in order to deploy to a
    remote TorqueBox server.</para>

    <section id="include-torquebox-recipes">
      <title>Include TorqueBox recipes</title>
      <para>First, you should include the Capistrano recipes which support
      TorqueBox deployments. If you use Bundler, you should also include the
      Bundler recipes at this point.</para>

      <para><screen>require 'torquebox-capistrano-support'
require 'bundler/capistrano'</screen></para>
    
      <para><emphasis>Note:</emphasis> You will need to install the <varname>torquebox-capistrano-support</varname>
      gem
      if you are using the <varname>torquebox-server</varname> gem install, as it is not installed 
      by default.</para>  

      <para><screen><prompt>$</prompt> <command>jruby</command> <option>-S</option> <command>gem</command> <command>install</command> torquebox-capistrano-support</screen></para>
    </section>

    <section id="set-up-home-variables">
      <title>Set up <varname>home</varname> variable(s)</title>

      <para>Capistrano needs to know some details about how TorqueBox is
      installed on the remote server. Primarily, it needs to be able to locate
      JBoss and JRuby.</para>

      <para>If you've installed TorqueBox by unzipping the distribution, you
      only need to set <varname>:torquebox_home</varname> in your
      <filename>deploy.rb</filename>.</para>

      <para><screen>set :torquebox_home,    '/opt/torquebox/current'</screen></para>

      <para>If you have a non-standard installation of the TorqueBox
      components, you may instead set <varname>:jboss_home</varname> and
      <varname>:jruby_home</varname> individually.</para>

      <para><screen>set :jboss_home,        '/opt/jboss-as'
set :jruby_home,        '/usr/local/jruby'</screen></para>

      <para>Capistrano uses these values in order to control the TorqueBox AS
      process, deploy applications to the correct location, and execute
      Bundler on the remote server if required. If required, you may also set
      <varname>:jruby_opts</varname> variable to pass to all invocations of
      JRuby.</para>
    </section>

    <section id="configuration-application-variables">
      <title>Optionally configuration application variables</title>

      <para>Typical usage of Capistrano expects production values to be
      embedded into your application's <filename>torquebox.yml</filename>
      file. In the event you need to override some values when deploying with
      Capistrano, several application variables may be set. If these are not
      set, they will not be emitted by Capistrano into the
      <filename>*-knob.yml</filename> it deploys.</para>

      <table>
        <title>Application variables</title>

        <tgroup cols="2">
          <thead>
            <row>
              <entry align="center">Name</entry>

              <entry align="center">Description</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>:app_host</entry>

              <entry>String to use a the web virtual host.</entry>
            </row>

            <row>
              <entry>:app_context</entry>

              <entry>Application web context.</entry>
            </row>

            <row>
              <entry>:app_environment</entry>

              <entry>Hash of name/values for environment variables.</entry>
            </row>

            <row>
              <entry>:app_ruby_version</entry>

              <entry>Ruby compatibility version (defaults to 1.8)</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>

    <section id="configure-server-control-style">
      <title>Configure server control style</title>

      <para>The TorqueBox AS can be controlled in two different ways. By
      default, the init.d method is used, but using the bin/ scripts that ship
      with JBoss is also supported.</para>

      <formalpara>
        <title>init.d</title>

        <para>Using a /etc/init.d script, the TorqueBox AS can be integrated
        into the server's normal service boot sequence and controlled using
        standard tools and methods enjoyed by sysadmins. By default,
        Capistrano support assumes the init.d script is located at
        <filename>/etc/init.d/jbossas</filename>. If you use a
        differently-named script, simply specify it using the
        <varname>:jboss_init_script</varname> variable.</para>
      </formalpara>

      <para><screen>set :jboss_init_script,    '/etc/init.d/jboss-as7-custom'</screen></para>

      <para>When using an <filename>init.d</filename> script, it is assumed
      that other details, such as bind IP address, server configuration
      selection, and other details are set through
      <filename>/etc/sysconfig</filename> files.</para>

      <formalpara>
        <title>bin/ scripts</title>

        <para>If you do not have access to modify scripts under
        <filename>/etc/init.d</filename>, you may desire to simply use the
        <filename>run.sh</filename> and <filename>shutdown.sh</filename>
        scripts under <filename>$JBOSS_HOME/bin</filename> to control the
        server process. To enable this method of server control, you must set
        the <varname>:jboss_control_style</varname> variable.</para>
      </formalpara>

      <para><screen>set :jboss_control_style,    :binscripts</screen>When
      using <filename>bin/</filename> scripts, you may control additional
      server properties through your <filename>deploy.rb</filename>
      file.</para>

      <table>
        <title>Variables affecting bin/ script server control</title>

        <tgroup cols="3">
          <tbody>
            <row>
              <entry><varname>:jboss_bind_address</varname></entry>

              <entry><code>0.0.0.0</code></entry>

              <entry>The IP address to bind when launching the AS.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para></para>
    </section>

    <section id="sample-deploy-file">
      <title>Sample deploy.rb File</title>
      <programlisting language="ruby">
require 'torquebox-capistrano-support'
require 'bundler/capistrano'

# SCM
set :application,       "myapp.com"
set :repository,        "git@github.com:account/repo.git"
set :branch,            "torquebox-2.0"
set :user,              "torquebox"
set :scm,               :git
set :scm_verbose,       true
set :use_sudo,          false

# Production server
set :deploy_to,         "/opt/apps/myapp.com"
set :torquebox_home,    "/opt/torquebox/current"
set :jboss_init_script, "/etc/init.d/jboss-as-standalone"
set :rails_env,         "production"
set :app_context,       "/"

ssh_options[:forward_agent] = false

role :web, "www.myapp.com"
role :app, "torquebox.myapp.com"
role :db,  "torquebox.myapp.com", :primary => true 
      </programlisting>
    </section>

    <section id="perform-deployes-with-cap">
      <title>Perform deployments</title>

      <para>Once your application is setup and configured, and your deployment
      server is prepared, you can begin performing deployments as you normally
      would.</para>

      <formalpara>
        <title>Disable the AS</title>

        <para>TorqueBox AS can work behind another webserver such as Apache
        httpd. Capistrano supports placing a
        <filename>maintenance.html</filename> page to be served by Apache when
        you desire to take down the app server.</para>
      </formalpara>

      <para><screen>$ jruby -S cap deploy:web:disable</screen>Capistrano will
      provide instructions for setting up Apache to stop directing requests to
      the AS when the maintanence page is in-place. When using TorqueBox
      behind Apache, these rules normally should live in the
      &lt;VirtualHost&gt; section of your httpd.conf, instead of within an
      .htaccess.</para>

      <para><screen>ErrorDocument 503 /system/maintenance.html
RewriteEngine On
RewriteCond %{REQUEST_URI} !.(css|gif|jpg|png)$
RewriteCond %{DOCUMENT_ROOT}/system/maintenance.html -f
RewriteCond %{SCRIPT_FILENAME} !maintenance.html
RewriteRule ^.*$  -  [redirect=503,last]</screen></para>

      <formalpara>
        <title>Deploy the application</title>

        <para>The Capistrano deployment workflow can occur even if the
        TorqueBox AS is not currently running. Deployment will not
        automatically start the AS if it is not running. Deployment will also
        never restart the server, as new application deployments are
        automatically recognized by the running AS.</para>
      </formalpara>

      <para><screen>$ jruby -S cap deploy</screen></para>

      <para>To restart an application but not the server itself, use 
        <command>restart</command></para>

      <para><screen>$ jruby -S cap deploy:restart</screen></para>

      <formalpara>
        <title>Control the TorqueBox AS</title>

        <para>You can start and stop the TorqueBox AS independent of
        deployment activities. When started, all applications that were
        running when last shutdown will be redeployed.</para>
      </formalpara>

      <screen>$ jruby -S cap deploy:torquebox:stop</screen>

      <para>To start the TorqueBox AS and re-deploy all previously-running applications:</para>
      <para><screen>$ jruby -S cap deploy:torquebox:start</screen></para>

      <para>To restart the TorqueBox AS and re-deploy all previously-running applications:</para>
      <para><screen>$ jruby -S cap deploy:torquebox:restart</screen></para>

    </section>
  </section>
</chapter>
