Deploying with Capistrano.

Modern web development is done with modern tools. The tools today we use to manage our code are things like version control systems and deployment frameworks. Two of the most noteable of these are git and Capistrano.

What is Capistrano?

Capistrano is a deployment framework that allows you to take your version controlled projects and deploy them to arbitrary environments. It replaces the antiquated style of FTP'ing something up because it is superior in many ways. Some of those include:

  • It's easier to deploy
  • It is version controlled.
  • You can jump back to any release at any time.
  • It is an easily repeatable and less error prone process.
  • And more..

The Installation & Setup

Step 1.
Installing Capistrano is easy. The command to do so is:

gem install capistrano  

More Capistrano documentation is always availible.

We also want to do a rails-less deploy so let's install that Gem too.

gem install railsless-deploy  

You can get more documentation on doing a rails-less deploy here.

If you aren't a Ruby / Rails expert don't worry. Those commands and some cursory reading skills are all you need. I promise. This setup is not complicated.

Step 2.
Prep your project. To do this run the Capify command from your project root directory.

Capify .

# The above command produces this:
├── Capfile
└── config
    └── deploy.rb

..... #All your other files here

Let's take a look at the Capfile.

# Uncomment if you are using Rails' asset pipeline
# load 'deploy/assets'

# remove this line to skip loading any of the default tasks
load 'config/deploy'  

This file is responsible for loading Capistrano tasks. Since we are using rails-less deploy we need to prepend our capfile with:

require 'railsless-deploy'  

so go ahead and include that on line 1 above the first comment.

Alrighty, let's mozy on over and checkout the config/deploy.rb file. Here are the following settnings you should put in

set :application, "Your App Name"  
set :scm, :git

#Github Creds / Repo URL
set :repository, "https://username:password@github.com/MyRepo/project.git"

#Remote Server Username / PW
set :user, "super_secret_user"  
set :password, "user1234"

#Sudo options (Just in case you need root perms)
#set :use_sudo, false #defaults to true.
set :sudo_password, "user1234"

#1. enable pseudo_terminal for the un / pw functionality  
default_run_options[:pty] = true

#2. Set the server URL and the root folder to deploy to.
server "example.com", :app, :web, :db, :primary => true  
set :deploy_to, "/var/www/public"

after "deploy:create_symlink", "deploy:cleanup"

namespace :deploy do  
  task :start do ; end
  task :stop do ; end
  task :cleanup, :roles => :app, :except => { :no_release => true } do
    run "#{deploy_to}/composer install -d #{deploy_to}/#{current_dir}"
    run "chmod -R 777 #{deploy_to}/#{current_dir}/app/storage"
    # remove some junk files
    run "rm -f #{deploy_to}/#{current_dir}/app/storage/cache/*"
    run "rm -f #{deploy_to}/#{current_dir}/app/storage/views/*"
  end
end  
  1. This is a pseudo terminal
  2. This line tells Capistrano where your server is and what roles this server plays. Aka, this server is our web server, our app server, and our db server AND it is our primary deployment target. That means it's the default location for a cap deploy a command you'll see more of later. There is more on this topic here.

Lot's of stuff but we'll cover it all shortly.

Now that all of that is configured you can run the next command which will enter your specified deployment directory on the server and prep the file structure for a capistrano deployment.

cap deploy:setup  

once that's done you can verify your efforts were successful by typing cap deploy:check. This will check if the folder permissions for the deploy are correct and if all the gems and binaries are present on the local and remote server. If there are errors, fix them. Once you are done with all the errors you can just deploy with cap deploy. This deploys to your environment you previously set as the primary or default. If you want to deploy to a different preset environment just preceed deploy with the target staging environment like so: cap staging deploy.

Final Tips:

  • Get A list of help: cap -H
  • Find out all the tasks capistrano knows about: cap -T.
  • Find out more about a task: cap -e taskname.

That's the basics! If you have feedback or errata corrections feel free to chime in in the comments or message me on twitter!