The Brightbox Gem

The Brightbox Gem

The Brightbox gem is a set of Capistrano recipes designed to make it very simple to deploy and manage a Rails application on your Brightbox virtual machine.

For a step-by-step walkthrough on using the gem, see the HOWTO

Deprecated

This documentation is for the old deprecated version of the Brightbox deployment gem and only works with Capistrano 1.4. Version 2 of the gem supports Capistrano 2.0+ and has many improvements over the old gem. See the v2 gem documentation here for more details.

Assumptions

In order to make deploying an application as simple as possible, the Brightbox Capistrano recipes makes certain assumptions about how you'll be deploying your app:

Your Rails application is committed to your Brightbox machine's svn repository at svn+ssh://rails@username-001.vm.brightbox.net/home/rails/subversion/jeremysapp/<application name>/trunk
You'll be using Capistrano to deploy and manage your application. The deployment configuration will install your application in the default user’s home directory (/home/rails/<application name>) unless this is changed manually in the deploy.rb file.
Apache 2.2 is used as the webserver for static files and mod_proxy_balancer to balance incoming dynamic requests across your Mongrel application servers. The Apache configuration file will be created automatically.
Mongrel is used as the Rails application server.
Monit is used to manage and monitor Mongrel processes

If you exclusively use the GEM for deployment and management, you shouldn't have to worry about any of these requirements.

Some of these things, such as subversion repository and deployment path, can be easily changed by configuring the Capistrano config file (config/deploy.rb) before deploying.

Installing the gem

To use the gem you need to install it on your local machine (i.e the workstation or whatever from where you develop and deploy your Rails application). Installing the gem is really simple. Just run the following:

$ sudo gem install brightbox

Note: The gem also needs to be installed on your Brightbox, but this will already have be done for you.

Note: For OS X, the make tools need to be installed. To do this for Leopard, install "XCode Tools" listed under "Optional Installs" using your Leopard install CD and then run the "XcodeTools.mpkg" package.

The "brightbox" command

The brightbox command generates (or overwrites) the config/deploy.rb file in your Rails app. This is the file that defines several deployment parameters of your application and is the file that the Brightbox gem uses to determine the settings for your application when deploying.

The deploy.rb file is created using the brightbox command from a terminal on your local machine:

Usage: /usr/bin/brightbox [options] [args]
    -A, --apply-to DIRECTORY         Create a minimal set of scripts and recipes
                                     for use with capistrano to configure servers.
    -n, --name APPLICATION_NAME      Name of application.
    -d, --domain DOMAIN_NAME         Domain name for application.
    -i, --server SERVER_NAME         Hostname or IP address of your Brightbox virtual server

For example…

$ brightbox -A /Users/jeremy/Sites/myrailsapp -n myrailsapp -d www.mydomainname.com -i jeremy-001.vm.brightbox.net

Capistrano Tasks

Here are some common Capistrano tasks that you can run locally from your application root. e.g:

cap _1.4.1_ -a restart_mongrel_cluster

Task	Description
cold_deploy	Deploys your application to your Brightbox for the first time.
deploy	Deploy the latest version of your application
deploy_with_migrations	Deploy the latest version of your app, running any new database migrations first
reload_apache	Reloads apache on your Brightbox
start_mongrel_cluster	Starts your application on your Brightbox using Monit

restart_mongrel_cluster	Restarts your application on your Brightbox using MOnit
stop_mongrel_cluster	Stops your application using Monit
monit_status	Displays the status of your application
monit_reload	Reloads the monit daemon
reconfigure	Allow easy adding of mongrels or domain changes (in v0.24)

Passwordless access

The Capistrano tasks need to log into your Brightbox via ssh so they prompt for your ssh password rather a lot. To avoid this, you can setup an ssh authentication key. Alternatively, but not really recommended, you can tell Capistrano your password in the config/deploy.rb file:

set :password, "mysecretpassword"

Using an External Subversion Repository

The Capistrano tasks assume you're using the subversion repository on your Brightbox, but you can use any repository as long as it's accessible from both your local machine and your Brightbox.

Before deploying (but after running the brightbox command on your app) edit the config/deploy.rb file. Set the :repository config to whatever url you need, and specify your username and/or password:

set :repository, "svn://jimjones@svnrepository.com/myapp/branches/production"
set :svn_password, "koolaid"

There is walkthrough tutorial on using the Brightbox Capistrano recipes here.