visit our site

Capistrano delivery via Patch

In Development, Products

by Andriy Yanko by October 25, 2011

Today we’ll talk about lightweight deployment method for your applications via Capistrano.


Standard capistrano deployment via ‘cap deploy’ is quite sufficient, but the standard deployment isn’t very fast. Each time, you have to do following:

  • check out the code
  • create symbolic links
  • run your custom tasks
  • switch to a new release
  • reload your back-end (passenger, unicorn, etc) processes
  • reload your background (daemons, resque-workers, etc) processes
  • and run deployment notifications

On top of that, real projects are big and often have several megabytes of code. Sometimes, you need to quickly apply a ‘hotfix’ for a critical bug. Usually, a fix like that is small enough (containing only several lines of code) and affects only a part of the application. If so. it’s not necessary to restart the whole application – you need to restart only part of the running processes. In the end, you don’t need to go through the entire deployment process.

The simple, but NOT RECOMMENDED, solution is to go to each server, manually change bad code, and then restart the back-end processes. It’s a bad idea for many reasons:

  • you must change the same code N times where N is number of servers
  • it is painful to switch back to original code
  • it’s a boring process and so there’s always the opportunity for mistakes because of the human factors

But then, how can you deliver a ‘hotfix’ in the right way? Try another approach called, capistrano patch.

Create, deliver, check and apply patch!

It is clear that the patching procedure should contain the following four steps:

Step 1. Create

Save the differences between the original version and the ‘hotfix’ version in a patch file. In the UNIX world there are two well-known tools called diff and patch. The first one can generate the patch while the second one can apply it.

Step 2. Deliver

Deliver the patch file to each application server.

Step 3. Check

Before the actual patching run, first launch the patch in a dry run mode. That means pretending to apply and checking if the patch can be applied. Then, when something is wrong with the code, one server patching procedure stops. Thus, you will NOT have application servers with different code.

Step 4. Apply

This operation performs the actual patch applying, so your application code will be changed.
IMPORTANT: now you should restart the appropriate Ruby-processes to see the changes.


If your ‘hotfix’ doesn’t help, you are able to quickly revert the patch because the patch file is already on the server.
Then, you can just go to the server and apply the same patch in the reverse mode.

Capistrano Patch

To automate this process, we created set of handy Capistrano recipes in a form of Ruby gem.
Just install the capistrano-patch gem:

There are 4 simple recipes:

And one aggregated recipe:

Patch arguments are environment variables:

  • FROM – means revision/tag/branch from which the patch begins
  • TO – means revision/tag/branch to which patch ends

Patching flow examples

We assume you use Git for your project as the SCM and capistrano as the deployment tool.

Applying patch flow

Create a branch and fix the code there. Test the code afterwards. Merge ‘hotfix’ into master/stable branch when you are ready to deploy. Set a new tag. Now you can deploy via patch. Run:

or just use simple aggregated recipe:

It performs ‘create,’ ‘deliver,’ ‘check,’ and ‘apply,’ of previously described steps. On each step you’ll be asked to confirm the operation.

Reverting patch flow

You can revert changes if something goes wrong:

though it’s enough to simply run the next recipe, since the previously created patch file is already on the server and you don’t need to create and deliver it again:

The recipe will check the patch file before reverting and then will revert all changes. Again, you yourself are responsible for corresponding back-end process restarting.

Patching example


Use your normal deployment for feature delivery, and the capistrano-patch recipe when you need a ‘hotfix.’ The patch recipe can be handy if:

  • you need quickly to deliver fix
  • the fix is very trivial (e.g. tiny fix in Rail’s view)
  • the fix affects not running code (e.g spec file)


* Railsware is a premium software development consulting company, focused on delivering great web and mobile applications. Learn more about us.

Signup for our weekly newsletter

Want to get more of Railsware blog?

RSS Feed

We're always ready to help!

Contact us