ggomeze.com

The very first thing we need to do, is to install capistrano in our computer. Access your rails project root directory and run

gem install capistrano

Next, we need to capify our application. Run this for doing that:

capify .

This will create two files:
Capfile this is the “main” file that Capistrano needs. Just as “make” automatically loads “Makefile”, and “rake” automatically loads “Rakefile”, Capistrano looks for and loads “Capfile” by default. The default Capfile generated by capify is pretty minimal. All it does is load “config/deploy.rb” (see next)
config/deploy.rb this is the file that contains your Rails application’s deployment configuration. Rails prefers that all configuration go under the config directory, and so Capistrano tries to abide by that as much as it can by just pointing the Capfile at config/deploy.rb. So we’ll basically do all our tweaking in config/deploy.rb

If you look at the default config/deploy.rb file, you will see the required information is pretty minimal. Here my deploy.rb file for your domain.com application, using a git repository:

require "bundler/capistrano"

set :application, "yourdomain.com"
set :repository,  "git@yourdomain.com:yourdomain.git"

set :scm, :git
set :scm_username, "ggomeze"
set :runner, "ggomeze"
set :use_sudo, false
set :branch, "master"
set :deploy_via, :checkout
set :git_shallow_clone, 1
set :deploy_to, "/home/webapps/yourdomain"
default_run_options[:pty] = true

server "yourdomain.com", :app, :web, :db, :primary => true

# If you are using Passenger mod_rails uncomment this:
# if you're still using the script/reapear helper you will need
# these http://github.com/rails/irs_process_scripts

namespace :deploy do
  task :start do ; end
  task :stop do ; end
  task :restart, :roles => :app, :except => { :no_release => true } do
    run "#{try_sudo} touch #{File.join(current_path,'tmp','restart.txt')}"
  end
end

First line is important when deploying rails 3 applications to avoid some errors on deployment. If you are using Passenger (with nginx in my case), you will have to uncomment last block of code, as i did in my file.

In this deploy.rb file, we are basically saying where is the repository, the scm used (git in our case), and also the username that will be used to access the server. If you don’t set that field, it will try to connect as the same user name of your local machine. I recommend you use a different user than root for those actions. Make sure that user is properly setup, making sure the user is able to access the “home/webapps/yourdomain” directory, and also create new directories. A successful deployment with Capistrano will result in a directory structure like the following (where [deploy_to] is where you want Capistrano to be deploying to on your server):

[deploy_to]
[deploy_to]/releases
[deploy_to]/releases/yyyymmddxxxxxx
[deploy_to]/releases/...
[deploy_to]/shared
[deploy_to]/shared/log
[deploy_to]/shared/pids
[deploy_to]/shared/system
[deploy_to]/current -> [deploy_to]/releases/yyyymmddxxxxxx

Each time you deploy, a new directory will be created under the “releases” directory, and the new version placed there. Then, the “current” symbolic link will be updated to point to that directory. (For now, don’t worry about the shared directory; we’ll get to that eventually.)
You’ll need to make sure you’ve configured your web server (nginx in our case) to look at [deploy_to]/current/public as the root web directory for your application.

Next some info about capistrano. To make sure we have it installed, we can run this:

cap -H

and with this command, we will get a list of available tasks:

cap -T

You can get more in-depth help on any of them with the “-e” switch:

cap -e deploy:web:disable

Next, we can actually start using Capistrano to talk to the server. We’ll first need to ask Capistrano to set up the basic directory tree it will use:

cap deploy:setup

This will log into your server and do a series of “mkdir” calls. Note, though, that if you aren’t using sudo (e.g., you set use_sudo to false, in your deploy.rb), you’ll need to make sure the permissions on your deploy_to directory are okay. If they aren’t, deploy:setup will fail. To fix the permissions, you’ll need to log into your server and do a few invocations of chown to set the permissions.

Even if you are using sudo (or, maybe especially if you are using sudo), you may need to fix the permissions on the directories that deploy:setup creates. Make sure the directories have the right permissions for whichever user you are deploying as to write to them.

Now that we’ve got the skeleton of the directories in place, we can ask Capistrano whether we’ve got all the dependencies in place. This includes directory permissions, as well as programs that will be needed (both locally and remotely). It’s easy and painless to do:

cap deploy:check

Capistrano will check both your local and remote servers for a variety of things. If any of the dependencies are not met, you’ll get an error message indicating what the problems are.

Not a real deploy, but let’s do it this way. This will help to detect potential errors in our configuration. Let’s start pushing things out to the server. This will copy your source code to the server, and update the “current” symlink to point to it, but it doesn’t actually try to start your application layer:

cap deploy:update

Are you ready to run the command that actually will deploy your application to production??. Really?. There you go:

cap deploy

I will probably cover personalization of config/deploy.rb file in next posts. As you know, you can create new tasks there, that will be run as part of deployment process. For example, what about keeping just last 5 releases?

Ger