======= HOWTO Deploy your Rails app with the Brightbox Gem =======

===== Pre-requisites =====
You'll need your rails application code committed to a change control repository.  If you don't have a subversion repository of your own, one comes pre-installed on your Brightbox VM at the url: ''svn+ssh://rails@username-001.vm.brightbox.net/home/rails/subversion''.  You'll also need subversion tools installed on your local machine.

We're going to assume that that you're using this repository, but it can be anything supported by Capistrano - you'll just need to manually set the '':repository'' directive in the ''config/deploy.rb'' file before running the deploy tasks.

The recipe runs the ''db:schema:load'' rake task on first deploy so it assumes you have a Rails database schema ''db/schema.rb''.  It also assumes you'll be running in production mode on your Brightbox VM.


===== Importing your app to your Brightbox svn repository =====
Each Brightbox contains a subversion repository, so to use it you'll need to import your app. For example (all on one line):

<code>
svn import /Users/jeremy/Sites/jeremysapp/trunk \
svn+ssh://rails@jeremy-001.vm.brightbox.net/home/rails/subversion/jeremysapp/trunk -m "initial import"
</code>

You'll obviously then have to check it out from that location and do your deployment from there.

===== Edit config/database.yml =====
Configure your production database to use the Brightbox SQL service.  Your database name should be prefixed with your Mysql username and an underscore.  Commit this config to your subversion repository.  The Brightbox Capistrano recipes will create this automatically if necessary.

<code>
production:
  adapter: mysql
  database: <your_mysql_username>_dbname
  username: <your_mysql_username>
  password: <your_mysql_password>
  host: sqlreadwrite.brightbox.net
</code>

All the info you require for the database config above should be contained in your welcome email.


===== Install the Brightbox gem on your workstation =====
The Brightbox gem contains some Capistrano recipes for deploying to Brightbox VMs.  Install it on your workstation.  It also needs to be on the server, but this is pre-installed for you.

<code>
sudo gem install brightbox
</code>

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.

===== Install any gems your application needs =====
You should install any gems your application needs on your Brightbox VM now.  [[docs:Ssh|ssh]] in as the rails user and run:

<code>
sudo gem install ferret hpricot other-package
</code>

Many common gems are already pre-installed, but you need to make sure all the ones you need for your app are good to go.

===== Run the Brightbox script on your application root =====
The gem provides a script named ''brightbox'' which will Capistranoify your application and preconfigure it with some sensible defaults.  You need to tell it the name of your application (one word, no spaces), the primary domain name to be used to access it (your vm hostname or perhaps a domain you've setup) and the hostname of your Brightbox VM:

<code>
brightbox -A /path/to/your/rails/app/trunk -n yourappname -d www.yourdomain.com -i username-001.vm.brightbox.net
</code>

As described above, it assumes your code is in your Brightbox subversion repository at ''svn+ssh://rails@username-001.vm.brightbox.net/home/rails/subversion/yourappname/trunk''.  If this is not the case, now is the time to change the '':repository'' setting in ''config/deploy.rb'' (in your local rails root).


===== Run the setup task =====
The ''setup'' task will create all the usual Capistrano stuff on your Brightbox VM - it's the default built-in Capistrano setup task.  If you've not used Capistrano before, you run these tasks using the ''cap'' command from within your applications rails root.

<code>
cap  _1.4.1_ -a setup
</code>

This will create the basic directory for your app in ''/home/rails/myapp''.  It will create a ''/home/rails/myapp/shared'' directory for any files that will need to be kept in-tact between deployments (logs and sessions for example, though other things, like uploaded images, can be configured too).


**Note**: The ''_1.4.1_'' part is needed when you have Capistrano 2.0 or later installed.  If you're still running a 1.4 version of Capistrano, drop the ''_1.4.1_'' part.  A version of the gem with Capistrano 2.0 support will be available shortly.



===== Run the cold_deploy task =====
The ''cold_deploy'' task does the initial setup of your app, such as creating the database for you, loading your schema and running migrations.  It then does a normal deploy of the app from your subversion repository and starts up the mongrels for you using Monit.

<code>
cap _1.4.1_ -a cold_deploy
</code>

What you'll now have is the latest code from your repository checked out into a timestamped directory on your Brightbox, such as ''/home/rails/myapp/releases/20071102120329'', and this has then been symlinked into ''/home/rails/myapp/current/''.  The shared stuff (currently just the logs and pids directories) have then been symlinked into there.

**You should only run the ''cold_deploy'' task once, when you first deploy your application**, otherwise you could lose data.  To deploy an updated version of your app, always use the ''deploy'' task.

===== Bask in the reflected glory of your running rails application =====

Visit the domain you specified in your browser - your app should now be live!


===== Deploying a new version of your app =====

When you've checked some changes to your subverison repository, just run the ''deploy'' task to deploy the latest code:

<code>
cap _1.4.1_ -a deploy
</code>

This skips all the database setup and Apache/Monit configuration that the ''cold_deploy'' task did.  It just checks out the latest code into a timestamped directory, symlinks it to current and restarts yours mongrels.

If your changes include some database migrations, run the ''deploy_with_migrations'' task instead:

<code>
cap _1.4.1_ -a deploy_with_migrations
</code>

**Note**: The ''deploy_with_migrations'' task does not work quite the same way as the usual ''deploy'' task.  If the deploy fails it does not try to roll back to the previous deployment, because migrations aren't guaranteed to be reversible.  It does not set up the maintenance page during the deployment either, but this will change in a future version of the gem.


===== Deploying additional apps =====

By default, the Brightbox Capistrano recipes configure two Mongrel processes running on ports 9200 and 9201.  When deploying more than one applications, you will need to manually change this port in the ''config/deploy.rb'' file in your rails root (created by the ''brightbox'' command).

Change the '':mongrel_port'' directive to another unallocated port (leave space for the number of mongrels you'll be running).  Do this after running the ''brightbox'' command but before you run the ''cold_deploy'' task.

Ensure the application name you use is unique for each deployment.  You'll also obviously need a unique domain name for each app too.  For testing purposes there is a wildcard hostname set up for all brightboxes.  So for example, all the following hostnames resolve to the same machine automatically:

<code>
mysecondapp.myuser-001.vm.brightbox.net
anotherhostname.myuser-001.vm.brightbox.net
themightyboosh.myuser-001.vm.brightbox.net
</code>