A Capistrano extension for Magento 2 deployments. Takes care of specific Magento 2 requirements and adds tasks specific to the Magento 2 application.

$ gem install capistrano-magento2

1. Add the following to your project's Gemfile:

   source 'https://rubygems.org'
   gem 'capistrano-magento2'

2. Execute the following:

    $ bundle install
   

1. Install Capistrano in your Magento project:

   $ cd <project_root>
   $ mkdir -p tools/cap
   $ cd ./tools/cap
   $ cap install

Note: By default, Capistrano creates "staging" and "production" stages. If you want to define custom staging areas, you can do so using the "STAGES" option (e.g. cap install STAGES=stage,prod). Built-in notifications (see below) confirm deploy action on both "production" and "prod" area names by default.

2. Update your project's Capfile to look like the following:

   # Load DSL and set up stages
   require 'capistrano/setup'
   
   # Load Magento deployment tasks
   require 'capistrano/magento2/deploy'
   
   # Load custom tasks from `lib/capistrano/tasks` if you have any defined
   Dir.glob('lib/capistrano/tasks/*.rake').each { |r| import r }

3. Configure Capistrano, per the Capistrano Configuration section below.

4. Configure your server(s), per the Server Configuration section below.

5. Deploy Magento 2 to staging or production by running the following command in the tools/cap directory:

   $ cap staging deploy

   or

   $ cap production deploy

Before you can use Capistrano to deploy, you must configure the config/deploy.rb and config/deploy/*.rb files. This section will cover the basic details for configuring these files. Refer to the Capistrano documentation and README for more details.

1. Configuring config/deploy.rb

   Update the :application and :repo_url values in config/deploy.rb:

   # Something unique such as the website or company name
   set :application, 'example'
   # The repository that hosts the Magento 2 application (Magento should live in the root of the repo)
   set :repo_url, '[email protected]:acme/example-com.git'

2. Configuring config/deploy/*.rb files

   Capistrano allows you to use server-based or role-based syntax. You can read through the comments in the file to learn more about each option. If you have a single application server then the server-based syntax is the simplest configuration option.

   • Single application server

     If your stage and production environments consist of a single application server, your configuration files should look something like this:

     config/deploy/production.rb

     server 'www.example.com', user: 'www-data', roles: %w{app db web}
     
     set :deploy_to, '/var/www/html'
     set :branch, proc { `git rev-parse --abbrev-ref master`.chomp }

     config/deploy/staging.rb

     server 'stage.example.com', user: 'www-data', roles: %w{app db web}
     
     set :deploy_to, '/var/www/html'
     set :branch, proc { `git rev-parse --abbrev-ref develop`.chomp }

   • Multiple application servers

     Refer to the "role-based syntax" comments in the config/deploy/*.rb files or to the Capistrano documentation for details on how to configure multiple application servers.

For the sake of simplicity in new project setups :linked_dirs and :linked_files are pre-configured per the following.

set :linked_files, [
  'app/etc/env.php',
  'var/.setup_cronjob_status',
  'var/.update_cronjob_status',
  'pub/sitemap.xml'
]

set :linked_dirs, [
  'pub/media', 
  'var/backups', 
  'var/composer_home', 
  'var/importexport', 
  'var/import_history', 
  'var/log',
  'var/session', 
  'var/tmp'
]

If you would like to customize the linked files or directories for your project, you can copy either one or both of the above arrays into the config/deploy.rb or config/deploy/*.rb files and tweak them to fit your project's needs.

A pre-built deploy routine is available out-of-the-box. This can be overriden on a per-project basis by including only the Magento 2 specific tasks and defining your own deploy.rake file under lib/capistrano/tasks in your projects Capistrano install location.

To see what process the built-in routine runs, take a look at the included rake file here: https://github.com/davidalger/capistrano-magento2/blob/master/lib/capistrano/tasks/deploy.rake

Before deploying with Capistrano, you must update each of your web servers to point to a current directory inside of the :deploy_to directory. For example: /var/www/html/current Refer to the Capistrano Structure to learn more about Capistrano's folder structure.

All Magento 2 tasks used by the built-in deploy.rake file as well as some additional commands are implemented and exposed to the end-user for use directly via the cap tool. You can also see this list by running cap -T from your shell.

This gem specifies terminal-notifier as a dependency in order to support notifications on OS X via an optional include. To use the built-in notifications, add the following line to your Capfile:

require 'capistrano/magento2/notifier'

After checking out the repo, run bundle install to install dependencies. Make the necessary changes, then run bundle exec rake install to install a modified version of the gem on your local system.

To release a new version, update the version number in capistrano/magento2/version.rb, merge all changes to master, and then run bundle exec rake release. This will create a git tag for the version (the tag will apply to the current HEAD), push git commits and tags, and push the .gem file to rubygems.org.

Note: Releasing a new version of the gem is only possible for those with maintainer access to the gem on rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/davidalger/capistrano-magento2.

This project is licensed under the Open Software License 3.0 (OSL-3.0). See included LICENSE file for full text of OSL-3.0.