A lot of folks use Capistrano to move their code to production servers. Using TorqueBox doesn't mean you have to change the way you deploy. We include modifications to the regular Capistrano recipes, plus a few extra to make life easier when deploying to a TorqueBox server.
Hot Deploy is Cool
TorqueBox is an application server, not simply a set of libraries to bind your application to HTTP traffic on port 80.
Instead, you toss your app at the already-running app-server.
From TorqueBox's point of view, your application isn't special. It's just yet-another-thing it needs to wire up and make available. TorqueBox (and JBoss) can serve many applications simultaneously, adding, removing and redeploying each along its own lifecycle.
This all happens without restarting the server, using hot deploy. Hot deploy allows the app-server to notice when an application has been added, removed, or updated, and responds correctly.
This means that Capistrano has slightly less work to perform when deploying an application. It'd be bad form to restart the server, in fact. TorqueBox ships with adjustments to the standard recipes to behave appropriately.
TorqueBox ships with support for Capistrano, but Capistrano itself is not installed by default. You'll need to install it into your local system (not the system you're deploying to).
Along with the
capistrano gem, you should also ensure a few other
gems are installed:
jruby -S gem install jruby-openssl ffi-ncurses capistrano
Capify your application
Make sure you are in the root of your application's tree, and invoke
capify on the current directory:
jruby -S capify .
capify command above created a new file under
deploy.rb. This is where your Capistrano deployment
is primarily controlled.
The first thing we need to do is import the TorqueBox recipes
deploy.rb file. If your application uses Bundler,
now is a good time to include Bundler's recipes also.
require 'org.torquebox.capistrano-support' require 'bundler/capistrano'
A few standard variables need to be set to control the general operation of Capistrano for your application.
set :application, "testapp" set :repository, "." set :user, "bob" set :deploy_to, "/home/bob/apps/testapp" set :deploy_via, :copy set :use_sudo, false
In the above, my application is named
testapp, and it will
be deployed simply by copying the contents of my local workspace
across to the server, into the
apps/ directory within my home directory
on the deployment server.
I've also instructed Capistrano to not use sudo.
You may certainly use repository-based deployment strategies with Capistrano, having it check code out of a Subversion, Git, or other repositories.
Also, set up the typical role-to-server mappings so that Capistrano
knows where your application is hosted, and where your database is
kept. Here, I'm deploying to a linux server named
that is running inside VMware:
role :web, "captest.local" role :app, "captest.local" role :db, "captest.local", :primary => true
Even though we don't typically restart the server after deploying your application, we do need to occasionally control the server and we definitely need to know where we should put deployments.
We need to know the locations of JBoss and JRuby on the remote server.
If you simply unzipped the TorqueBox distribution somewhere, set
:torquebox_home to this location, and we can figure out where
JBoss and JRuby are from there.
set :torquebox_home, '/home/bob/torquebox-current'
If you have a non-standard installation, you may set
set :jboss_home, '/opt/jboss' set :jruby_home, '/usr/local/jruby'
Remember, all of these
_home paths reference paths on the remote
server, not your local machine.
Controlling TorqueBox AS with Capistrano
In the event you do need to start or stop the TorqueBox AS, you have two options:
JBoss includes a variety of
init.d scripts in the distribution
$JBOSS_HOME/bin/ directory. You may find the one
appropriate to your platform and use it under
By default, the TorqueBox Capistrano recipes assume an
script is used to control the server. When you issue commands
jruby -S cap deploy:start or
jruby -S cap deploy:stop,
instead of trying to manage a pack of mongrels (or whatever),
Capistrano will send the appropriate signals to the
If the default init.d script name of
jbossas is not appropriate
for your deployment strategy, you may adjust the location of the
script using the
set :jboss_init_script, '/etc/init.d/my-fancy-jboss'
Occasionally you might want to control TorqueBox AS not through
init.d, but directly using the
bin/run.sh scripts. This is
useful on systems where you might not have
bin/ script, simply set the
set :jboss_control_style, :binscripts
deploy:stop will use
bin/shutdown.sh to control the server.
Once you've accomplished the basic setup, deployment to TorqueBox using Capistrano works as you might expect.
jruby -S cap deploy
Code will be moved to your production server, the
will be created, a basic
*-rails.yml will be created.
If your server is already running, then you're done!
If your server is not running, that's okay. You can deploy and undeploy apps irrespective of the current state of the server.
When you want to start the server, and all apps already deployed to it:
jruby -S cap deploy:start
The recipe to deploy the
*-rails.yml file writes the barest
deployment descriptor possible, only setting
Your application should include a
set details for your application, such as
Additionally, web configuration, such as virtual-host or
context path settings should be included.
When developing locally, and using the
task, these values are generated for you, defaulting to the
development environment. When using Capistrano to deploy,
you need to ensure that production versions of these values
application: RAILS_ENV: production web host: myawesome.com context: /
The majority of the adjustments TorqueBox brings to Capistrano involve deployment of application code and lifecycle-management of the app-server.
Everything else should work-as-expected, assuming you are using tyipcal configurations.
For example, if you have Apache
httpd in front of your TorqueBox
server, the traditional
mod_rewrite strategy for controlling
a maintenance page still works.
The various steps Capistrano takes to perform a deployment are still directly invokable for piece-meal execution.
jruby -S cap deploy:update_code jruby -S cap deploy:symlink jruby -S cap deploy:migrate jruby -S cap deploy:web:enable