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.
Each Brightbox contains a subversion repository, so to use it you'll need to import your app. For example (all on one line):
svn import /Users/jeremy/Sites/jeremysapp/trunk \ svn+ssh://rails@jeremy-001.vm.brightbox.net/home/rails/subversion/jeremysapp/trunk -m "initial import"
You'll obviously then have to check it out from that location and do your deployment from there.
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.
production: adapter: mysql database: <your_mysql_username>_dbname username: <your_mysql_username> password: <your_mysql_password> host: sqlreadwrite.brightbox.net
All the info you require for the database config above should be contained in your welcome email.
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.
sudo gem install brightbox
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.
You should install any gems your application needs on your Brightbox VM now. ssh in as the rails user and run:
sudo gem install ferret hpricot other-package
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.
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:
brightbox -A /path/to/your/rails/app/trunk -n yourappname -d www.yourdomain.com -i username-001.vm.brightbox.net
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).
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.
cap _1.4.1_ -a setup
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.
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.
cap _1.4.1_ -a cold_deploy
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.
Visit the domain you specified in your browser - your app should now be live!
When you've checked some changes to your subverison repository, just run the deploy task to deploy the latest code:
cap _1.4.1_ -a deploy
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:
cap _1.4.1_ -a deploy_with_migrations
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.
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:
mysecondapp.myuser-001.vm.brightbox.net anotherhostname.myuser-001.vm.brightbox.net themightyboosh.myuser-001.vm.brightbox.net