photo credit: Lyon via photopin (license)

The art of deployment

(please note, that the original dutch article I write can be found here)
A website is worthless if it can’t be visited online. To achieve this it has to be uploaded to a server: it has to be deployed. Often, the task of deploying a website is thought of to be a simple thing: you connect to a server, upload some files, done! But as your projects get complexer, updates are on a more frequent base and there are more than one programmers on a project, a mistake is right around the corner. Because of this, it’s necessary to have a good solid solution for deploying your website.

Humans make mistakes

For me, it’s a constant struggle to improve this part of the job. Especially if you’re a developer in a team with multiple developers, you don’t want the scenario where programmer A updates a site, programmer B overwrites this update and programmer C is working on a feature based on old code. Not to mention the part of uploading the files to a server where sometimes files are forgotten or older files are not deleted.
Above example immediately shows a big problem: humans make mistakes. Therefore it’s a logical step to not let a human deploy or update a website, but leave it to a computer. After all, computers are used to perform repetitive tasks over and over again, and an update for a website is nothing more than a repetitive job.


A nice piece of software I’m lately quite enthusiastic about is Capistrano. There are more solutions out there aimed at deploying and updating websites, but this one fits best in my current workflow.
It’s quote easy to use Capistrano (given that you’re familiar with shell-environments) and it offers hooks before or after a deployment on a very low level.


One important aspect of Capistrano is it’s use of a sub-versioning system. In my case that’s Git. What Capistrano does is nothing more then taking a specific branch of your repository and put it’s source code in a folder on your server. As easy as it sounds, it immediately tackles a some common mistakes when uploading files from an individual workstation:

  • You don’t know if other developers made some updates in between
  • You can easily forget to upload a file (or delete an old file)
  • You can accidentally overwrite files that shouldn’t be overwritten (think about configuration files)

By using a Git-repository you eliminate these risks because a programmer always has to push it’s changes to the repository first. If then a conflict emerges it has to be solved first, otherwise it can’t be pushed nor deployed. Simple as that!
A rule of thumbs for webdevelopment with Git is that the master-branch must always be equal to the code of the live website on any given moment. In my workflow I use more branches (like staging, development, feature-branches, etc) but that’s outside the scope of this article.

Capistrano in 5 simple steps

To prepare Capistrano for your project is easy as 1-2-3. By following the next 5 steps you already have a basic setup for Capistrano in your project:

1. SSH Key

If you don’t (yet) have a SSH-key on your local workstation you need to create one. A SSH-key provides a safe way to connect with another computer. It exists of two parts: a private and a public key. The private key is stored on your local workstation, and the public key is put on the machine you wish to connect with.
To create a SSH-key on your local workstation you must enter the following command:

Of course you fill in your own e-mail address here. A couple of questions are asked like where to store the key and which password you want to use.
With the next command you can read your public key (and copy/paste it to your clipboard):

2. User account on the server

On the remote server you can add a new user, or you can add your public key to an existing user. This user is going to be used as the UNIX-user for copying files and creating directories. If you want to create a new account this can be done as following:

The second command makes sure the user is ‘locked’. This means that the user cannot login on the server with the usual username/password-method, but only with SSH-keys.

3. Add your public key

On the server, make sure you’re logged in as your deployment-user (‘deploy’) in our example. In his home-directory, create a folder called .ssh  (if it doesn’t already exist), and in this folder create a file called authorized_keys . In this file you can paste your public key. Make sure the rights of authorized_keys  are set to 0600 and that of the .ssh -folder to 0700:

If all went well, you will now be able to login with SSH on this server, without being prompted for a password. You can test this by trying to connect to the server from your local machine. If you’re not being prompted for a password, you did it right:

4. Install Capistrano

Of course (if you haven’t already) you need to have Capistrano installed on your local machine:

In your project-root, initialize a new capistrano-project:

Capistrano will create some files automatically. The most important files are config/deploy.rb , which contains the global deployment-parameters, and config/deploy/*.rb , which contains different deployment profiles (one for production and one for staging for instance).
The most important part is to set the correct repository and server data in deploy/config.rb :

In deploy/config/production.rb  you can put your profile-specific settings. For example:

If all went well, you can now deploy your entire site with one simple command:

Capistrano will now automatically connect with your server, pull your repository from your Git repository and checkout the master-branch and put it in the folder you assigned it to. The folder structure has various folders, like current , shared  and releases .

  • current  is a symbolic link to your latest release.
  • releases  contains a x-amount of releases (you can specify this in your deployment profile).
  • shared  allows you to share assets between your various deployment profiles, or store assets, like user uploads.

Note that Capistrano threats each deployment as a whole new release. This means that any previous stored or changed files in your current release won’t be available in the new  release. Therefore it’s important to store anything that might change live (like uploads, but also session or cache-files) is not stored in current , but in shared . Usually these files are the same files you would ignore in your repository.
Because of above folder structure, and the maintaining of an x-amount of releases, rolling back an update when something went wrong is extremely easy:

5. Tasks to perform after deployment

To execute tasks after a deployment (for example: renaming files or flushing a cache-folder), you can add tasks in Capistrano to perform after a successful deployment. The following example renames the configuration-file and flushes the cache folder:

In conclusion

This is just a simple how-to about the power of Capistrano. Of course there are multiple paths to achieve a goal but I hope this article shows how convenient and powerful a certain solution can be.
This article doesn’t cover everything. We haven’t even looked at databases for example; which are always a crucial point in each form of version control or deployment management. In future articles we will look more in-depth on how to deal with those but for now this is a nice starting point for those who are unfamiliar with Capistrano or deployment software.

(please note, that the original dutch article I write can be found here)

Visitors give this article an average rating of 3.0 out of 5.

How would you rate this article?

2 thoughts on “The art of deployment”

  1. marcobax22 says:

    Good stuff Giel !

  2. Moshe says:

    Thanks for your article. I success to deploy my app using capistrano but any reason my server don’t access the current/releasses files and folders…
    When I browse to my-app.com/current i can access my webiste, but if I browse to my-app.com I just get the files and folders tree…
    Do you have any idea what wrong?

Leave a Reply