Deploy 12-factor applications with Capistrano
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Deploy 12-factor applications using Capistrano.


Add this line to your application's Gemfile:

gem 'capistrano-buildpack'

And then execute:

$ bundle

Or install it yourself as:

$ gem install capistrano-buildpack


Here's a basic Capfile that uses Capistrano::Buildpack:

require 'rubygems'

set :application, "bugsplatdotinfo"
set :repository, ""
set :scm, :git
set :additional_domains, ['']

role :web, ""
set :buildpack_url, ""

set :user, "peter"
set :base_port, 6700
set :concurrency, "web=1"

read_env 'prod'

load 'deploy'
require 'capistrano-buildpack'

This will load a file named which should consist of environment variables like this:


This example just unconditionally loads 'prod' but you can have as many different sets as you want, loading them as appropriate in tasks.

To run a deploy:

$ cap deploy:setup # create the required directory structure and gem install foreman-export-nginx
$ cap deploy       # actually run a deploy

Deploy will do the following things:

  • Create the required directory structure at /apps/<application>
  • Clone/update the buildpack
  • Clone/update the code repository
  • Apply the buildpack to the code repository
  • Create upstart-style init files in /etc/init and start up the app
  • Create an nginx config file at `/etc/nginx/conf.d/.conf and restart nginx

The nginx config will list at least one domain for the app: <application>.<hostname>, which in this case is Anything you add to the :additional_domains setting gets tacked on at the end.

Several other settings are available:

  • use_ssl: true to listen on port 443
  • ssl_cert_path: a path to a certificate file on the server. You are responsible for getting the certificate there.
  • ssl_key_path: a path to a key file on the server. You are responsible for getting it there.
  • force_ssl: Force a redirect to SSL. This will unconditionally redirect to the first domain in additional_domains, so if you have multiple you may want to do this in your app instead.
  • force_domain: Force a redirect to the given domain.
  • default_server: Declare that this app is the default for this server. Can only have one per nginx.

To run your app as a different user than :user, use the :app_user setting. This user will not be created for you, you'll need to create it yourself, and it must have a proper home directory.

Running remote commands

Sometimes you want to run a command on the other end that isn't defined in a Procfile. Do that with cap remote:

$ cap remote echo hi there

Very Important Notes

Capistrano::Buildpack will not run bin/release from the buildpack, so any environment variables that that attempts to set need to be set using read_env. In addition, at the moment the exported nginx config does not have compression turned on.


Email patches to