Deploy Your Code With Capistrano 3

Introduction

Capistrano is a Ruby program which can do a lot of things for you when you want to deploy your website. It provides many tools but I will focus on the simplest one: we will see how to tell Capistrano to copy your code from you source control repository to your server using a SSH tunnel. It goes without saying that you need a working SSH access to your server.

Installing Capistrano 3 on your computer

This step is quite easy if you already have Ruby and RubyGems installed on your computer. If not, you will find a lot of tutorials on the internet. Then, you can get the Capistrano gem by running the following command:

$ gem install capistrano

Now, go to your application’s root directory and install Capistrano:

$ cap install

That will create multiple directories and files including a file named Capfile and a template deployment recipe at config/deploy.rb. You can delete the lib/ directory as we won’t need it in that tutorial. You don’t need to edit the Capfile, just open config/deploy.rb in your favorite text editor and delete everything except the first line (with the lock directive). We’ll see how to fill it correctly.

Configuring Capistrano

I’m going to assume that you’re using Git (but you can adapt that tutorial to SVN or Mercurial) and that you have a master and a production branch. Start by adding that to your config/deploy.rb file:

set :application, 'your_app_name'

Then, you have to tell Capistrano how to reach your Git repository:

set :scm, :git
set :repo_url, 'git@bitbucket.org:your_login/your_repo.git'

Capistrano also needs to know where to deploy your code on the server, so you should add something like this:

set :deploy_to, '/var/www/root_directory_of_your_app'

Also add these convenient options for a nice output when deploying:

set :pty, true
set :format, :pretty

You are done with the config/deploy.rb file. As we’re not going to use multiple stages (it’s very useful but the goal of this tutorial is just to set a basic working Capistrano environment), we only have to fill the config/deploy/production.rb file (you can delete the other files in that directory). A good practice is to create a new user named deploy on your server with the correct permissions. Again, delete everything in that file and add the following lines:

set :stage, :production
set :branch, "production"
role :app, %w{deploy@your_server_ip}
server 'your_server_ip', user: 'deploy', roles: %w{app}

You also need to configure Capistrano for SSH. I personally prefer disabling the password authentification, so the following configuration will work only if the deploy user has your public key:

set :ssh_options, {
  user: 'deploy',
  port: 22,
  forward_agent: true,
  auth_methods: %w(publickey password),
  password: 'please use keys'
}

Thanks to the forward_agent line, your Git repository won’t need your server’s public key but only your personal one.

Running Capistrano

Here comes the fun. To validate your configuration, run the following command in the root directory of your application:

$ cap production deploy:check

Capistrano will create the initial directory structure on your server for future deployments. If there’s anything wrong with your configuration, you will get error messages. The output Capistrano gives you will help you a lot to find and correct the problem. If you didn’t get any error, congratulations! Capistrano is now ready to do all the work for you.

To deploy your code from your production branch, all you have to do is running the following command:

$ cap production deploy

That’s all! Capistrano will create a new subfolder containing the last version of your code in your server’s release folder and make the current symlink point to it, so don’t forget to update your webserver’s Document Root.

You have reached the end of this very short tutorial. For your information, Capistrano can also perform pre and post-deploy functions like running database migrations or restarting a webserver. You can also set multiple stages for you deployment in addition to production (development, testing, etc.) and link them to your corresponding Git branches. It’s only a matter of patience and configuration : the more you want Capistrano to do things for you, the harder it is to configure it correctly. Good luck!