Recipe 13.8. Deploying Your Rails Project with Capistrano

Problem

Contributed by: Matt Ridenour

You would like to automate the deployment of your Rails project to your production server. The production server is configured with either Apache or Lighttpd and FastCGI.

Solution

NOTE

Although Capistrano can run on Windows, it cannot deploy to Windows-based production servers.

First, install the Capistrano gem:

~$ sudo gem install capistrano

Use the cap command to prepare the Rails application for deployment:

~$ cap --apply-to /Users/Mattbot/development/blog

The cap utility installs a deployment file called deploy.rb in your project's config directory. Open config/deploy.rb in your editor, and find the "REQUIRED VARIABLES" section. Find the set :application line, and set the right-side value to your project's name. The project for this recipe is called "blog". Directly below the :application variable is the :repository variable. Set that to the URL of your Subversion repository. Local file URLs, such as file:///Users/Mattbot/svn/blog are not allowed; you must use a repository accessible via svn, ssh and svn, or http.

Your settings should look similar to those below:

set :application, "blog" set :repository, "ssh+svn://matt@mattbot.net/Users/Mattbot/svn/blog"

Next, select the server roles used for deployment. We will deploy to a single computer, so all the roles will be assigned to the same server. In the "ROLES"

section, assign the server to the web

, app

, and db

roles:

role :web, "mattbot.net" role :app, "mattbot.net" role :db,  "mattbot.net"

Be sure to set the :user variable in the "OPTIONAL VARIABLES" section to the username of your account on the production server, if it differs from the username of the account on the system from which you are deploying your project:

set :user, "matt"

If you are using Apache, add the following lines to the end of the file:

desc "Restart the Apache web server" task :restart, :roles => :app do   sudo "apachectl restart graceful" end

Once you save the file, you are ready to begin. Run the following rake task to create the project's directory structure on the server:

~/blog$ rake remote:exec ACTION=setup

You will be prompted for a password to the production server; enter it to continue.

Now run the rake command to commence deployment:

~/blog$ rake deploy

Enter the production server's password again. Capistrano now installs the latest version of your project to the production server. The default path to the project on the production server is /u/apps/your_application_name

(for this example, /u/apps/blog

If Capistrano encounters any errors during deployment, it will rollback any changes it has already made and revert the production server to the previously deployed version of your project, if available. If you have accidentally deployed a version of your project that incorporates new bugs, you can manually roll back the deployment with the following command:

~/blog$ rake rollback

Discussion

This recipe is somewhat misleading. Capistrano (formerly known as SwitchTower) is far more than just a web application file-transfer program. It's a general-purpose utility for executing commands across many servers at once. These commands (called tasks) can execute any system administration task you can put in a shell script. Tasks can be assigned to subsets of the servers and can be conditional. All run from a single command. Very powerful stuff.

Like Rails, Capistrano requires your adherence to a few simple conventions to minimize the configuration requirements. Be sure you comply with the following before you begin:

You are deploying to a remote server or servers.
Your user account on the server has administrative access.
You are using SSH to communicate with your servers.
Your servers have a POSIX-compliant shell, such as bash or ksh. Windows, csh, and tcsh cannot be used.
If you use multiple servers, all the servers share a common password.
For Rails deployment, your project must stored in a version control repository that is network accessible. If you have not already created a version-control repository for your project, read Section 1.10" and do so now.

In the "OPTIONAL VARIABLES" section of the deployment recipe, you can tailor some of the default settings to better suit your needs. Capistrano places the project in a directory called /u/apps/your_project_name on the servers. It may make more sense to change this to something that better fits your server's directory structure. Uncomment the set :deploy_to line and change the deploy_to variable to the path you want your project installed to on your servers. For example, on Mac OS X, you might prefer:

set :deploy_to, "/Library/WebServer/#{application}"

You may have been terrified to see your password echoed to the screen during the rake remote:exec ACTION=setup step. Install the termios gem to suppress this behavior. Loose lips sink ships.

~/blog$ sudo gem install termios

Capistrano's setup task creates a new directory structure on the production server. This structure is different from the standard Rails directory structure. Take a minute to examine the new directories. Under your project's main directory, you'll find a directory called releases, which contains copies of each of your project's deployments. There's a subdirectory for each deployment named after the UST time it was deployed. Also in the project's main directory, you'll find a symbolic link named current linking to the current release. From the main directory, your project's logfiles are symlinked within the shared/log so they persist between deployments.

As the number of servers in your load balancing plan grows, Capistrano can still deploy everything with a single rake deploy command. Assign the new servers to the appropriate roles. You are not limited to three servers when you assign the role variables, nor are you limited to three roles. Define new servers and roles as you need them.

role :web, "www1.mattbot.net","www2.mattbot.net" role :app, "rails.mattbot.net", "www2.mattbot.net" role :db,  "7zark7.mattbot.net", :primary => true role :db,  "1rover1.mattbot.net" role :backup, "mysafeplace.mattbot.net" desc "Move backups offsite." task :offsite_backup, :roles => :backup do   run "scp 7zark7.mattbot.net:/backups/* /backups/7zark7/" end

New tasks can be run independently via rake:

~/blog$ rake remote:exec ACTION=offsite_backup

Task creation is a large subject beyond the scope of this recipe but definitely a recommended area for further investigation if you find Capistrano's deployment abilities useful.

Problem

Solution

Discussion

See Also