====== 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, [[docs:thebrightboxgem:howto|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. [[docs:gemv2:start|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:

<code>
$ sudo gem install brightbox
</code>

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:

<code>
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
</code>

For example...

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


===== Capistrano Tasks =====

Here are some common Capistrano tasks that you can run locally from your application root. e.g: 
<code>
cap _1.4.1_ -a restart_mongrel_cluster
</code>

^ 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:

<code>
set :password, "mysecretpassword"
</code>

===== 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:
<code>
set :repository, "svn://jimjones@svnrepository.com/myapp/branches/production"
set :svn_password, "koolaid"
</code>

===== More =====
There is [[docs:thebrightboxgem:howto|walkthrough tutorial on using the Brightbox Capistrano recipes here]].