Capistrano is a very useful open-source tool for deployment automation written in Ruby. You don’t have to log in to your servers and execute the same commands over and over again. The tool I’m going to present you today allows you to execute scripts that will do everything for you. In my opinion the most important advantages of Capistrano are:

  • modularity – there are many modules that will help you implement Capistrano to your project,
  • extensibility – it’s not a problem to add your own functionalities by writing rake scripts,
  • stability – when Capistrano deploys changes, it’s done in a separate folder and the current symlink is changed to an adequate release only once the whole process is successful*,
  • ease of use – the basic configuration is very easy and you can quickly start using the tool.

*) some files and folders are shared (adequate symlinks are created as per the configuration) between the releases to avoid potential problems, for example with the configuration of the store or user sessions.

What you need

You will need the package manager RubyGems to start.

Bundler isn’t necessary, but it will allow you to install packages in the project folder and always use the same packages version.

You can install Bundler via gem using the following command:

$ gem install bundler

How to start

Create a tools folder in your Magento 2 project and add a file called Gemfile:

source ''
gem 'capistrano-magento2'

Next, execute the following command in the folder magento2/tools/:

$ bundle install --path ./gems

It will download capistrano-magento2 and all necessary dependencies. Additionally, a new file called Gemfile.lock will be created with the information about dependencies and required packages versions.

Your next step will be to add Capistrano configuration to your project. Let’s create a new folder magento2/tools/cap and execute the following command inside:

$ bundle exec cap install

The command should generate a few files – the most important are the ones from the config folder. The deploy.rb file includes the general configuration for all environments to which you want to make deployment. By default, it simply includes the application name and the address of the repository from which you want to download the changes. In the same folder, you’ll find the deploy folder where you will store the configuration of selected environments. You can store here, for example, information about the address of the server where you will deploy changes, the path of your files or the branch you want to use. You can freely add new files describing your servers.

Apart from the environment configuration, capistrano-magento2 gives you variables for Magento 2. For example, :magento_deploy_themes will allow you to deploy only selected themes and with :magento_deploy_languages you can select the deployed language/locale.

The above variables are very helpful when you want to make a deployment to a server with limited resources – if you don’t select a theme, too much RAM will be required to execute setup:static-content:deploy on the instance AWS EC2 t2.micro which I used for the first tests of the tool.

In case of limited storage, it’s also worth decreasing the default value for :keep_releases. Keeping 5 releases on a server isn’t usually necessary, you should be fine with only 3.

Additionally, because Capistrano works based on SSH, you can execute commands on the server from your local terminal. You can check the list of available commands using:

$ bundle exec cap -T

Now, instead of logging in to the server to clean the cache, you can simply execute a command via Capistrano!

The only thing left is to execute Capistrano deploy command and wait for the results:
$ bundle exec cap deploy

It may be hard to believe, but this is all you need for automatic deploy via Capistrano. Once you get familiar with the tools, it’s worth considering further deployment automation so that you don’t need to write any commands, but that’s a topic for a different article.

capistrano –
capistrano-magento2 –