Ruby on Rails deployment is often regarded as a dark art. But the guys at Brightbox have made it simple with their Brightbox gem. I have recently moved three clients over - so I’m getting pretty good at deploying there. Here are the steps that I follow:

One:

Sign up with Brightbox and buy a box. You will need to know the account name, the ‘rails’ user password and the mysql password - all of which are available from the VM details page that is emailed to you. The brightbox will be provisioned with a name similar to “account-001.vm.brightbox.net”. I recommend ssh’ing into the box and changing the ‘rails’ user’s password - you will be typing it a lot - or installing your ssh keys.

Two:

Prepare your application in subversion.

You need to make sure that your config/database.yml file is included in your subversion repository (many developers prefer to leave it out for team reasons - don’t worry, you can take it out again later).

You should edit the production entry to point at your desired production database. Set the database name to account_database (where account is your Brightbox account name and database is whatever you want), set the user to your account name, the password to whatever you noted down above and the hostname to sqlreadwrite.brightbox.net (the Brightbox MySql cluster).

Don’t forget to set the svn:ignore property on your log and tmp folders.

Three:

Install the Brightbox gem on your development machine.

Use the brightbox command to generate the Capistrano file (telling it your application name, the name of your Brightbox and the desired domain name that your application will be running on).

At the same time, point your domain name (via an A record) at the Brightbox’s IP address and place a support ticket to set up a Reverse DNS entry (if you will be sending out emails). If you don’t have a domain name yet then use myapp.account-001.vm.brightbox.net.

Then open config/deploy.rb and edit the source code repository entry to point at your svn server (if necessary setting up scm_username and scm_password entries).

Four:

Run the cap setup command (if you have capistrano 2 installed, this becomes cap _1.4.1_ setup as, at the time of writing, the cap 2 version of the gem is still in beta). This will ssh into your server (so you will need that password) and set up the folder structure for you.

Then run the cap cold_deploy command. This tests whether things are working - as it tries to get your code out of svn and onto the server, sets up monit (to keep tabs on your app), uses the database.yml file to create a database and configures Apache with your domain name. If it fails you will need to edit your deploy.rb (and probably get rid of the created database so you can run it again).

You should see your application at your domain name. Stop a second and reflect on how much you have achieved :-).

Five:

Remove your database.yml from svn (set the svn:ignore property on it). Then copy it to the Brightbox (using scp) and place it in /home/rails/my_app/shared/ (where my_app is obviously your application’s name). If you have any file uploads (attachment_fu) or shared assets then copy them into the shared folder as well. Then edit your deploy.rb to add something similar to the following:

task :after_update_code do

  # link the relevant database.yml from the shared folder to the app's folder

  run "ln -nfs #{deploy_to}/#{shared_dir}/database.yml #{release_path}/config/database.yml"

  # link the file store to the application

  run "ln -nfs #{deploy_to}/#{shared_dir}/files #{release_path}/public/public"

end

This means that, after deployment, capistrano will create symlinks from your shared database.yml and shared files into your applications config and public folders respectively.

Six:

Try another deployment to test your symlinking. cap _1.4.1_ deploy - if all goes well then your application should still be running at your domain name, and monit will report that your processes are running correctly. From now on, all you need to do is commit to svn and then cap _1.4.1_ deploy.

I’ve found out what the shared host problem was. I must have upgraded my local copy of Capistrano to the latest. Which changes the permissions used on deployment - instead of 755 they are 775. This causes problems on shared hosts because it effectively means you can execute scripts on other people’s accounts. So a patch has been submitted for Capistrano and you need to add the following to your deployment script.

task :set_permissions do donothing = trueend

I’ve given up on shared hosting - too many variables. Instead I’ve invested in a VPS - meaning I have had to delve into the world of Linux (Fedora 6) administration.

First off, I had to set up my applications to run under mongrel (rather than the FCGI of your typical shared host). I followed the instructions in the “Agile Web Development” book - basically gem install mongrel and gem install mongrel_cluster on both your development box and the server. I also created a new user on the server that mongrel would run under - we wouldn’t want your application running as root would we? Add require ‘mongrel/recipes’ to your Capistrano script and include the line set :mongrel_conf, “#{current_path}/config/mongrel_cluster.yml”. If you are using my staging server instructions then you will probably need to change this - for example I have a mongrel_cluster_live.yml and a mongrel_cluster_test.yml. To create the mongrel_cluster configuration file go to your rails root folder and type mongrel_rails cluster::configure -e production -a 127.0.0.1 -N 3 -p 8000 -c /home/user/applications/current. This creates your mongrel_cluster.yml file - in this case with the production environment, listening to (the server’s) local address, with three processes starting on port 8000 (so 8000, 8001, 8002) deployed to /home/user/applications on the server (the current is the symlink that Capistrano creates).

Run through your normal Capistrano deployment procedure - you should see that the last stage is mongrel_rails cluster::start - in the example above it will attempt to start three mongrel processes on the server on ports 8000, 8001 and 8002. If all has gone well you should be able to point your browser at those three ports and see your application.

Next up is getting your front-end web-server to connect to these mongrel processes. I’m using Apache 2.2 with mod_load_balancer (again as described in the Agile Web Development book) - this is so that requests for myapp.com on port 80 get routed to one of the mongrel processes. This requires editing /etc/httpd/conf/httpd.conf (back this file up before touching it!). Firstly, tell Apache about your mongrel processes:

Proxy balancer://myapp_mongrel BalancerMember http://127.0.0.1:8000 BalancerMember http://127.0.0.1:8001 BalancerMember http://127.0.0.1:8002/Proxy

This attaches the name myapp_mongrel to the three mongrel processes we set up earlier. Then we create a virtual host with the following RewriteRule attached:

 RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f RewriteRule ^/(.*)$ balancer://myapp_mongrel{REQUEST_URI} [P,QSA,L]

This means that any request coming to Apache for myapp.com (or whatever your virtual host is called) is dealt with dynamically (Apache cannot find a static file to serve up in its place) is automatically passed to myapp_mongrel - which we have defined as http://127.0.0.1:8000..8002. So Apache forwards the request to one of your three mongrel processes which deals with it and returns the response back to Apache. Note that we could even set up the Mongrel processes to run on one or more different servers if we desired, spreading any really heavy loads across multiple machines.

This is all good, and nothing too unusual - as I say it’s mostly taken directly from the Agile Web Development book.

However, I also wanted my mongrel processes to start up automatically, should I need to restart the server. So I added some scripts to /etc/init.d. As I said before I had created a separate user for the mongrel processes - I don’t want any security issues compromising the entire server if I could help it. So my start up script (/etc/init.d/myapp - and don’t forget to chmod +x) was slightly different to most.

#!/bin/bash

case “$1″ in start) echo “starting myapp” su - user -c “mongrel_rails cluster::start -C /home/user/application/current/config/mongrel_cluster.yml” >> /var/log/messages ;; stop) echo “stopping myapp” su - user -c “mongrel_rails cluster::stop -C /home/user/application/current/config/mongrel_cluster.yml” >> /var/log/messages ;; restart) echo “restarting myapp” su - user -c “mongrel_rails cluster::restart -C /home/user/application/current/config/mongrel_cluster.yml” >> /var/log/messages ;;esac

Log in as root and try /etc/init.d/myapp restart - you should see mongrel stopping and then restarting. A quick ps aux should reveal your mongrel processes running under the correct user. Genius.

What is happening here is the use of su (switch user). By using su - username (the hypen is important) the script switches user to “username” and loads username’s environment. Then the mongrel_rails command is run - explicitly passing it the configuration file that it needs to use. All output is passed to /var/log/messages for analysis later.

Lastly, we need to tell Fedora to run our script on startup.

Edit /etc/rc.local

/etc/init.d/myapp start

And that is it - getting your application deployed on linux using mongrel and apache. My only other step was to firewall off all ports except SSH and Web - so that no-one could access the mongrel processes directly.

Capistrano is one of my favourite Rails features. It’s vital to “agile” development - there’s no point running through your iterations, making fast, small changes, if you can’t easily get them into the hands of the (hopefully) paying public. (It’s also a major reason I’m not too interested in deploying on IIS any more).

However, one of the things I have found is that sometimes you get stuff that runs fine on your local boxes but fails on your server (I had a weird one where Bluecloth worked fine here but not there - despite freezing all my Gems and Rails itself).

So I wanted to set up an intermediate deployment on my server.

A quick hunt found Mike Burn’s article which I then adapted for my own purposes.

Firstly - created a new subdomain and database on my server - and a folder for deploying to.

Then I added a new environment file - /config/environments/staging.rb - this was a copy of development.rb but with code caching turned on.

Next, I set up a new database configuration in /config/database.yml - staging: that points to my newly created staging database.

To get Capistrano to deploy correctly, I amended /config/deploy.rb like so:

if stage == “production” set :deploy_to, “/home/user/myapp_live”else set :deploy_to, “/home/user/myapp_staging”end

I also needed to adapt things after the code had been copied, so the following was added to the end of deploy.rb:

desc “After updating the code, back up the database and migrate”task :after_update_code do run “/home/user/mysql/backup.sh”  # if this is a staging deployment, switch the environment to staging, not production  if stage == “staging”   # switch to the staging environment   run “sed -i ’s/\”production\”/\”staging\”/’ #{release_path}/config/environment.rb”   # migrate the database   run “cd #{release_path} && rake RAILS_ENV=staging db:migrate” else   # migrate the database   run “cd #{release_path} && rake RAILS_ENV=production db:migrate” endend

Basically, I did not trust the deploy_with_migrations task to work the way I wanted it to (I kept noticing rake RAILS_ENV=production db:migrate appearing in the log).

So instead I back up my database manually using a script and then - if I’m in production mode I just migrate the database (explicitly setting the Rails Environment). However, if I’m in staging mode then I use sed to change my environment settings (so that the line ENV[”RAILS_ENV”] ||= “production” becomes ENV[”RAILS_ENV”] ||= “staging”) and then migrate the database (explicitly setting the Rails Environment).

One final step - I created two shell scripts - deploy and deploy_to_production that look like this:

# deploy#! /bin/shcap -S stage=staging deploy# deploy_to_production#! /bin/shcap -S stage=production deploy

These call Capistrano’s deploy task, setting an internal variable stage to “staging” or “production” respectively.

Further Enhancements - I’m going to change deploy.rb so that it uses different Subversion Urls for staging and production - so staging pulls from http://mysvn/myapp/staging and production pulls from http://mysvn/myapp/live.