Capistrano series - configuring Capistrano #1

We're at a crucial stage with our Ruby on Rails with Capistrano stack as we have all the pieces installed and a lot has been configured.

Now we need to look at the Capistrano configuration file and see what needs adding.


In this article, I have taken quite a bit of space to try and explain what each setting is, and what it does.

As such, don't be put off by the apparent length of the article as, by the end of it, you will understand and have a good grasp of what is happening when you use Capistrano.


If you are not in the rails application folder, then move there now (remember this is on your local workstation and not on your Slice):

cd ~/dev/project1

The location may vary depending where on your workstation you have placed the rails application.

Let's get straight on and open up the Capistrano deploy file:

nano config/deploy.rb

The default file looks like this:

set :application, "set your application name here"
set :repository,  "set your repository location here"

# If you aren't deploying to /u/apps/#{application} on the target
# servers (which is the default), you can specify the actual location
# via the :deploy_to variable:
# set :deploy_to, "/var/www/#{application}"

# If you aren't using Subversion to manage your source code, specify
# your SCM below:
# set :scm, :subversion

role :app, "your app-server here"
role :web, "your web-server here"
role :db,  "your db-server here", :primary => true

Fairly simple and, apart from a few additions, is sufficient to get started.

Application, user and repository

Seem logical to start at the top of the file and work our way down so the first thing is the application name.

This can be anything you like. However, it makes a lot of sense to use the domain name as the application name.

This means that the 'application' variable can be used further on in the file and it keeps in line with the protocols we are already using when naming vhost files, etc.

So, set the application name as follows:

set :application, ""

Next we will add a variable for a username. It's important you set a user here as permission issues often arise from using your local workstation username instead of the Slice username.

Add this line straight after the application variable:

set :user, "demo"

For the repository, enter the same details that you used to check out project1:

set :repository,  "svn+project1ssh://"

SSH port

One essential setting that is not mentioned is how to define the SSH port.

When Capistrano connects to your Slice via SSH it will use port 22 (the default SSH port). However, when we setup the Slice, we defined the SSH port to be 30000.

Capistrano needs to know about this.

Setting the port is as simple as:

set :port, 30000

Deployment path

Now the SSH port has been set, we can set the deployment path.

When we setup the Slice and Nginx vhosts, we used the public_html folder in our home directory.

We've already set the application name (see above) so we can use that variable again.

So the next line to add is this:

set :deploy_to, "/home/demo/public_html/#{application}"

Note the use of the 'application' variable at the end of the entry. If we changed the 'set :application' name, that change would be reflected in this setting.

App, web and db

The final 3 settings (at this stage) are shown as 'app', 'web' and 'db'.

The vast majority of users will have all 3 variables pointing to the same place so it can seem a little confusing to have 3 settings here as if they are different things.

However, do remember that you can have your database (db) on another Slice and so on. These settings are then very useful as it tells Capistrano where the db is, where the app is and so on.

As an aside, we can define a new variable here and call it 'location'. We can then assign a URI to that variable and use it in all 3 settings.

So this section could look something like this:

set :location, ""

role :app, location
role :web, location
role :db,  location, :primary => true

That is one way of doing it and I mention it as an option for you to play with.

For this example though, I am simply going to use the 'application' variable as everything is happening on the single Slice.

As such, the 3 settings will look like this:

role :app, application
role :web, application
role :db, application , :primary => true

Completed file

So this is what the completed deploy.rb will look like:

set :application, ""
set :user, "demo"
set :repository,  "svn+project1ssh://"

# If you aren't deploying to /u/apps/#{application} on the target
# servers (which is the default), you can specify the actual location
# via the :deploy_to variable:
# set :deploy_to, "/var/www/#{application}"

set :port, 30000

set :deploy_to, "/home/demo/public_html/#{application}"

# If you aren't using Subversion to manage your source code, specify
# your SCM below:
# set :scm, :subversion

role :app, application
role :web, application
role :db, application , :primary => true

Still pretty basic as this stage (there is lot more we can do later on) but it is enough to enter our first Capistrano command...


Before we enter the first command, let's log into our Slice and move into the public_html folder:

ssh -p 30000 demo@

cd /home/demo/public_html

Unless you already have a working Slice, the directory is going to be empty:


That produces no output as the folder is empty.

Well, let's enter our first Capistrano command and then have another look.


Back on our local workstation (not the Slice!) we can now enter:

cap deploy:setup

Pretty minimal stuff.

However, exciting things are taking place and this really shows not only the power, but the ease of using something like Capistrano.

So what happened?

Well, let's take another look at the public_html folder on the Slice:


That's new.

Directory Structure

What Capistrano has done is really quite clever.

It's logged into the Slice and, using the settings from the deploy.rb file, has created a directory structure that will be used for future deployments.

Inside the parent folder are two folders called 'releases' and 'shared'.

Inside the 'shared' folder are permanent folders for the logs, pids and system info.

So from one command, Capistrano is now ready to deploy the application.



We've configured the deploy.rb file that Capistrano uses to setup and deploy our application.

Then, using a single command, we created the directory structure that will be used for future deployments.

A lot has happened, but now that we are more familiar with the deploy.rb file, we can move on to deploying the application.


Article Comments:

Dave commented Sun Jan 20 16:22:13 UTC 2008:

Awesome set of articles here. I've gotten up to speed in no time flat thanks to this excellent custom service you're providing.

Looking forward to the second installment!

BobbyL commented Sat Feb 09 06:54:39 UTC 2008:

Great job PickledOnion!

One thing however...

I believe that this would be a good place to add a step for setting up a shared/config/database.yml. Most of us have the told subversion to ignore the database.yml file.

Hariharan Venkata commented Sun Feb 24 22:41:24 UTC 2008:

Here is my setup i am using

set :application, "" set :user, "demo" set :repository, "svn+project1ssh://<ipaddress>/home/demo/repository/project1" set :port, <portnumm>

set :deployto, "/home/demo/publichtml/"

role :app, application role :web, application role :db, application, :primary => true ++++++++++++++++++++++++++++++++++++++++++ I get the following error.

cap deploy:setup servers: [""] connection failed for: (Errno::ECONNREFUSED: Connection refused - connect(2))

++++++++++++++++++++++++ When i comment the set :port, 8848 line i get a prompt to enter the password and then i get this error.

Password: connection failed for: (Net::SSH::AuthenticationFailed: demo)


Hariharan Venkata commented Mon Feb 25 17:22:19 UTC 2008:

I get the following error when i run cap deploy:setup command.

connection failed for: project1 (SocketError: getaddrinfo: No address associated with nodename)

I am following the instructions given at slicehost at this link.

Here is the setup of my deploy.rb file

set :application, "project1" set :user, "username" set :repository, "svn+project1ssh://" set :port, port_num

set :deployto, "/home/username/publichtml/#{application}"

role :app, application role :web, application role :db, application, :primary => true

I have created a tunnel in my ~/.subversion/config file as shown below

project1ssh = /usr/bin/ssh -p port_num -l username

When i run the command cap deploy:setup i get the following error

cap deploy:setup executing `deploy:setup' executing "umask 02 && mkdir -p /home/username/publichtml/project1 /home/username/publichtml/project1/releases\ /home/username/publichtml/project1/shared /home/username/publichtml/project1/shared/system /home/username/publichtml\ /project1/shared/log /home/username/publichtml/project1/shared/pids" servers: ["project1"] [DEBUG] Mon Feb 25 09:06:09 -0800 2008 -- transport.session: connecting connection failed for: project1 (SocketError: getaddrinfo: No address associated with nodename)

What does this error mean and how can i fix this?

Hariharan commented Tue Feb 26 21:48:40 UTC 2008:

fixed the by changing the application name from project1 to the ip address.

connecting connection failed for: project1 (SocketError: getaddrinfo: No address associated with nodename)

Brian commented Thu Mar 06 20:01:10 UTC 2008:

I'm a little confused about your file structure. In the previous article you checked out 'project1' folder to ~/dev/ and then created a rails app called 'project1' in the checked-out 'project1' folder, so you path would be '~/dev/project1/project1'.

When you start this article you specify the path as ~/dev/project1.

Should the project1 folder you checked out from subversion be filled with a rails app called 'project1' or should it be the root folder with app, config, db, etc.


PickledOnion commented Fri Mar 07 10:05:47 UTC 2008:

Hi Brian,

I didn't create the project1 rails app inside the checked out project1 folder.

I created it in the dev folder containing the project1 folder.

As such, all the rails components would be created inside the checked out project1 folder.

I'll see if I can make that clearer in the article.


Brian commented Sat Mar 08 07:05:46 UTC 2008:

O ok. I see now, I think it's a little confusing because they are both named project1. Thanks for the help!

BobbyL commented Fri Mar 14 04:23:21 UTC 2008:

Quick question:

Can you the ip address in placed of the location above?

set :location, "123.456.789.1"

Would this work?

Nicos commented Wed Apr 02 13:46:13 UTC 2008:

If you're running cap in Windows, make sure you've got Pageant running to perform the SSH authentication (if you're not using passwords).

nick commented Wed May 07 01:04:36 UTC 2008:

i kept getting this error:

* [err ::] sudo: no passwd entry for app!

i fixed it by adding this to deploy.rb:

set :runner, "myusername"

Joel commented Thu May 08 05:54:53 UTC 2008:

I'm wondering if the requirement for the runner is new.

Fixed my problems too - made it easy as pie :)

Randito commented Mon May 19 21:52:47 UTC 2008:

Had the same "no passwd for app" error. Fixed it with the "set :runner, user" fix.

More information here.

cmar commented Wed Jun 11 10:48:21 UTC 2008:

I was setting up a new rails app on a hardy slice and ran into the same issue of "no passwd for app". The "set :runner, user" seemed to fix it.

Thanks for all the help!

Ian commented Sun Nov 02 00:21:21 UTC 2008:

Thanks Hariharan , I was having the same problem. That fixed it. :-)

zorn commented Mon Feb 15 18:54:32 UTC 2010:

When I did the cap deploy:setup command I ended up with directories that were owned by root,thus my later cap deploy:cold failed due to permissions. One way to fix this seems to be adding set :use_sudo, false to the deploy.rb file as seen on:

Want to comment?

(not made public)


(use plain text or Markdown syntax)