JBoss.orgCommunity Documentation

Chapter 19. TorqueBox Capistrano Support

19.1. What is Capistrano?
19.2. Installing Capistrano
19.3. Capify your Application
19.3.1. Basic deploy.rb configuration
19.4. TorqueBox-specific deploy.rb configuration
19.4.1. Include TorqueBox recipes
19.4.2. Set up home variable(s)
19.4.3. Optionally configuration application variables
19.4.4. Configure server control style
19.4.5. Sample deploy.rb File
19.4.6. Perform deployments

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).

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.

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.

$ jruby -S gem install jruby-openssl ffi-ncurses capistrano

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

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

$ jruby -S capify .

This creates a Capfile in the root of your application, which delegates to another file it created: config/deploy.rb. The deploy.rb file is the primary location for configuring your deployment strategy.

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

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

Disable the AS

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

$ jruby -S cap deploy:web:disable

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 <VirtualHost> section of your httpd.conf, instead of within an .htaccess.

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]
Deploy the application

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.

$ jruby -S cap deploy

To restart an application but not the server itself, use restart

$ jruby -S cap deploy:restart
Control the TorqueBox AS

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.

$ jruby -S cap deploy:torquebox:stop

To start the TorqueBox AS and re-deploy all previously-running applications:

$ jruby -S cap deploy:torquebox:start

To restart the TorqueBox AS and re-deploy all previously-running applications:

$ jruby -S cap deploy:torquebox:restart