I recently started digging into the world of Ruby on Rails and quite early came across Capistrano. The whole idea and concept of Capistrano could be explained with their own quite catchy tagline “Welcome to easyish deployment“.
I’ve been doing deployment using Git for a while by now. But I find Capistrano more flexible and reliable. Since Capistrano is intended to be used with Ruby on Rails it doesn’t work with other platforms “out-of-the-box“. But magic can still occur with a few lines of code.
Below you’ll a “step-by-step” tutorial on how the get started using Capistrano for easier deployment. The whole idea for this post came in mind during a Capistrano setup for a Codeigniter application I did recently. But I don’t see why this deployment process wouldn’t be applicable on any other platform or framework.
This tutorial assumes you already got your code hosted using either SVN or Git. You preferaly have setup public ssh keys between your computer and the server you’re deploying to. You’re using the same directory structure as below for your applications on your server (feel free to change the Capfile in order to match your existing structure).
/var/www/example.com /var/www/example.com/www.example.com /var/www/example.com/www.example.com/logs /var/www/example.com/www.example.com/public
Start of by installing Capistrano on your computer. Capistrano is distributed as a Ruby gem.
$ sudo gem install capistrano
Next up clone my default Capfile (Capistrano config file) using cURL. Or use the Gist below.
$ curl "http://gist.github.com/raw/353124/ceda1eccacee7604d7180b23ff20cb618cb760af/capfile.rb" > Capfile
There are some variabels you need to change in order to make this Capfile work with your setup. Basically look through all lines that begins with “set” and change the corresponding value. Also make sure to change the server domain on line 10.
A typical Capistrano deployment is loaded with different kind of tasks. Since Capistrano is awesome it allows you to setup own tasks and even overwrite existing tasks.
As mentioned earlier Capistrano was invented with Ruby on Rails in mind, therefor we need to overwrite a few Rails specific tasks (migrate, restart, start). These default tasks are probably not compatible with your application. But feel free to rewrite them if needed.
As you might noticed by now the task “copy_config” inside Capfile isn’t a default task. My Codeigniter applications usually include some setup specific config files that shouldn’t be included in the repository by obvious reasons. For instance a config file including all necessary MySQL credentials. Therefor these files needs to be setup and edited manually in order to get the application running. But there’s one problem using this method with Capistrano.
Everytime you deploy using Capistrano a fresh copy of your latest application is being cloned/checkout from the repository and stored inside a new folder on the server. Since Capistrano doesn’t proceed from the previous deployed release all files that isn’t included in the repository will not be moved to the new deployed release folder. But no worries! Since Capistrano allows us to hook up our own tasks to specific events during deployment we can solve this problem with ease.
The task namned “copy_config” is being executed right after the “symlink” task. Right after the new release directory has been created and linked to the current directory. Since all my necessary config files are included in the “.gitignore” file we can use that as a reference and simply check if the file exists in the previous release folder. If so simply move the file to the newly created release folder. Capistrano provides some nifty variabels such as “previous_release” and “latest_release” to make this operation easier.
Any other needed operation to get your application up and running should probably be executed after the “symlink” task.
Once your Capfile is done it’s time to run a initial setup deploy. Start of by running the following command.
$ cap deploy:setup
You should end up with a similar directory structure on your server.
/var/www/example.com/www.example.com/public/releases /var/www/example.com/www.example.com/public/shared /var/www/example.com/www.example.com/public/shared/log /var/www/example.com/www.example.com/public/shared/pids /var/www/example.com/www.example.com/public/shared/system
It’s finally time to perform a first initial (cold) deploy of your application to your server.
$ cap deploy:cold
Congratulations! You just performed your first deploy using Capistrano. For future deploys the cold task isn’t necessary. Simply execute the command below.
$ cap deploy
Easy enough don’t you think?
This post should give you a brief idea of the Capistrano workflow. And show how you can hook up your own tasks in order to get your application up and running. I can’t guarantee that this method can be applicable on your application. As the title states “… almost anything“.
Interested in learning more about Capistrano? Here’s a few posts that I stumbled across and found interesting during research for this post.
Photo credit: heyskinny