Rails 5: Capistrano

Capistrano allows to deploy easily your application to remote servers and offers much more.

Rails:   5.0.0
Ruby:  2.3.0
OS:     Ubuntu 16.04


More details about Capistrano can be found here.


Capistrano allows to deploy application to remote servers. In this article we covers only some basics and in our case, we will deploy application from development server to single production server. Before we start, make sure that Rails and Ruby are installed in both servers already. We assume that you have already created a Rails project.


Capistrano installation

Add to Gemfile:

If you are using rbenv instead of rvm, please follow this capistrano-rbenv.

And run:



Capistrano deploys application from remote repositories (eg. from GitHub, Bitbucket, etc.). Before we continue, you should setup your git and use some host like Bitbucket to store your code there.

Before pushing project to remote repository (GitHub, Bitbucket), you can add sensitive files to .gitignore. Files and directories placed in .gitignore are not being pushed to remote repositories, what allows us to keep our passwords and keys in safe place. Mostly, two files are placed in .gitignore. Open .gitignore:

And add these files:


Capistrano setup

Capify application:

Following files should be created:



Add require ‘capistrano/rails’ after require ‘capistrano/deploy’ in Capfile:


In next step, we setup few things according to remote production server. Open config/deploy/production.rb and modify like below:

Change fake IP: on IP or domain of your remote server.


In config/deploy/production.rb we have set configuration for production remote servers. In config/deploy.rb file we can set global configuration, which can affect on all stages (production, staging etc.). Open config/deploy.rb file:

Change ‘enter_here…’ and set link to your repo on GitHuub/Bitbucket to :repo_url.


Additional setup

In previous part of post we covered the most basic configuration of Capistrano. Mostly, we’d like to add few more things to our configuration files. In this part we present some of the most common settings. More details about possible configurations you can find on Capistrano and Capistrano-rails.



Listed files will be symlinked into each release directory during deployment. It is used for files like database.yml.


Listed directories will be symlinked into the release directory during deployment. It’s useful in case of resources which should be shared independently to releases, like photos uploaded by users.

To add both linked_dirs and linked_files, open config/deploy.rb:


Authentication & Authorisation

Capistrano bases on SSH in deploying applications. Before we continue, you can create system users on remote servers:

But to keep it simple, we use root user account. Remember that the recommended way is NOT using root account!


The Capistrano needs automated authentication in two cases:

  1. From development machine (for example from our personal computer) to remote server (for example production server). It is done by ssh-agent.
  2. From remote server to BitBucket/GitHub repository, what is done by SSH agent forwarding.

Let’s set up both in following steps:

Development machine – remote server

We start from creating SSH key:

You will be asked 3 times:

  • for file name – you can leave empty and just hit Enter. If would you like to save the key in specific file, you can type for example: /root/.ssh/sc_production_rsa.
  • passphrase – remember it!
  • passphrase confirmation

Run ssh-agent and add to this agent your SSH key:

If you save key under specific name, instead of $ ssh-add use:

To check if key was added to agent:

In next step, we have to place the public part of our SSH key on each remote server (in our case we’ve got only one remote server).

Go to remote server…

Instead of use IP of your remote server.

Repeat it for every remote server if you have more than 1. You can now exit from remote server. Test if everything is OK:



Remote servers – repository

Capistrano uses SSH Agent Forwarding for that. You have to be sure only that ssh-agnet is running on your local machine and key is loaded:

To verify that capistrano has access to git, you can run following command (being in project directory):

If would you have any problems, you can check chapter Problem with connecting to repository on remote at the bottom of this article.



Because we use root account on remote machine, we can omit this part. However, you have to remember that it is not recommended to use root account and you should prepare custom user accounts. If you use custom user accounts on remote servers, you have to set up proper access rights to specific directories and services. More details about it you can find in Capistrano documentation.


Run Capistrano

Before we deploy, we can run follwoing command:

There can occur some problems. One of the most commons based on linked_files. Mostly there are files like database.yml or secrets.yml, which we added to .gitignore. We can move it manually for the first time.

To run deploy seriously, use following command:


Common problems

Some of the common problems, when running cap deploy. Remember that after changing project files, you have to commit changes and push to remote repository, because capistrano uses your code from GitHub/Bitbucket – not code from your local machine.

Devise secret key


You have to just open the config/initializers.devise.rb and add prompted line: config.secret_key = ‘ad…’.


Access to MySQL



You have to setup database.yml and secrets.yml for production environmet. Mostly, you have to set the user, password and keys in these both files.


No database




At the first deploy, you should get error about unknown database. It’s because Capistrano runs rake db:migrate on every deploy, but it doesn’t run rake db:create at the first deploy. So we have to do it manually. Log in to remote-production server. Go to /var/www/<your-project-name>/releases/<enter in one of the folders> and run following commang:


Tomasz Antas

Ruby on Rails developer and Web designer.
The area of his interest includes Popular Science, Internet of Things, Wearables, AI and Virtual/Augmented Reality.

Latest posts by Tomasz Antas (see all)

Thanks for reading!

  • virvivir

    well. thx so much for the tutorial. keep fighting