configuring Capistrano #1

Details

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.

deploy.rb

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, "domain.com"

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://123.45.67.890/home/demo/repository/project1"

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, "domain2.com"

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, "domain.com"
set :user, "demo"
set :repository,  "svn+project1ssh://123.45.67.890/home/demo/repository/project1"

# 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...

public_html

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

ssh -p 30000 demo@123.45.67.890

cd /home/demo/public_html

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

ls

That produces no output as the folder is empty.

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

deploy:setup

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:

ls
...
domain.com

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.

Nice.

Summary

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.