T H E T H E O R Y A N D I M P L E M E N T M A G E N T O 2 C A P I S T R A N O

D e p l o y M a g e n t o 2 C a p i s t r a n o M a g e n t o 2 C a p i s t r a n o Q u e s t i o n s C O N T E N T

D E P L O Y M A G E N T O 2 Update Repository Composer pull down Sync files Deploy static files Enable maintenance Enable modules

D E P L O Y M A G E N T O 2 Run setup scripts Clear cache Disable maintenance mode Update permissions Restart PHP FPM

C A P I S T R A N O s Capistrano is a framework for building automated deployment scripts Multiple stages Parallel execution Server roles Community driven It's just SSH

C A P I S T R A N O s Benefits: Deploy automatically Reduce risk for deploy process Easy to customize

C A P I S T R A N O s Prerequisite: Ruby version 2.0 or higher A project that uses source control Bundler, along with a Gemfile for your project Note: - Create a Gemfile by Bundle with 'bundle init' command.

C A P I S T R A N O s How it working: Connect to the server via forward SSH and pull down codebase. Create a release for each deploy time. The current project will refer to latest success release. Fallback to latest success release if deploy process to break down.

C A P I S T R A N O s Install: Add Capistrano to your project's Gemfile: group :development do gem "capistrano", "~> 3.8" end Capify project: bundle install bundle exec cap install

C A P I S T R A N O s Folder Structure: ├── Capfile ├── config │ ├── deploy │ │ ├── production.rb │ │ └── staging.rb │ └── deploy.rb └── lib └── capistrano └── tasks

C A P I S T R A N O s Configuring config/deploy.rb: set :application, 'example' set :repo_url, 'git@github.com:acme/example-com.git' Update the :application and :repo_url values in config/deploy.rb: For each stage, e.g 'config/deploy/production', set the branch and :deploy_to folder for pulling code: set :branch, 'master' set :deploy_to, "/var/www/my_app_name"

C A P I S T R A N O s Configuring config/deploy/*.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 } Single application server

C A P I S T R A N O s Customize tasks: namespace :magento2 do desc "Restart PHP FPM" task :restart_php_fpm do on roles(:all), in: :sequence, wait: 1 do execute :sudo, 'service php7.0-fpm restart' end end end Define helper tasks in lib/capistrano/tasks file. In my project, I also create a task for upload adminer.php file using for staging site.

C A P I S T R A N O s Project Structure: ├── current -> latest release ├── releases │ ├── 20170420014820 │ ├── 20170420014820 │ └── repo │ └── shared

C A P I S T R A N O s Usage: Single application server: bundle exec cap deploy # bundle exec cap production deploy Multiple application server: Refer to Capistrano documentation for detail on how to configure multiple application servers. List all available tasks: bundle exec cap -T

M 2 C A P I S T R A N O s Install Add the following to your project's Gemfile: source 'https://rubygems.org' gem 'capistrano-magento2' Useful gem: gem 'capistrano-composer' gem 'capistrano-upload-config' gem 'capistrano-file-permissions'

D E P L O Y S E T T I N G s Capistrano Built-Ins set :linked_files, [ 'app/etc/env.php', 'pub/.htaccess' ] set :linked_dirs, [ 'pub/media', 'var' ] For prepared config files and keep the resource sync between releases folders.

D E P L O Y S E T T I N G s Capistrano Built-Ins set :config_files, %w{app/etc/env.php pub/.htaccess} # push link files after check them exist. before 'deploy:check:linked_files', 'config:push' Using capistrano-upload-config gem to push them into the server Note: - Link files must be named as filename..extension, e.g env.production.json in the repository project.

D E P L O Y S E T T I N G s Magento Deploy Settings set :magento_deploy_setup_role, :all set :magento_deploy_cache_shared, true set :magento_deploy_languages, ['en_US'] set :magento_deploy_themes, [] set :magento_deploy_composer, true set :magento_deploy_production, true set :magento_deploy_maintenance, true set :magento_deploy_confirm, []

D E P L O Y S E T T I N G s Magento Deploy Settings Those tasks above for: - Role for primary host. - Cache operation. - Setup languages for theme. - Deploy static content files. - Enables composer install. - Enables production DI compilation. - Enables use of maintenance mode. - Used to require confirmation of deployment

D E P L O Y S E T T I N G s Magento Deploy Settings set :magento_deploy_chmod_d, '0755' set :magento_deploy_chmod_f, '0644' set :magento_deploy_chmod_x, ['bin/magento'] set :file_permissions_roles, :all set :file_permissions_paths, ["pub/static", "var"] set :file_permissions_users, ["SERVER_USER"] set :file_permissions_groups, ["SERVER_GROUP"] set :file_permissions_chmod_mode, "0777" before "deploy:updated", "deploy:set_permissions:acl"

D E P L O Y S E T T I N G s Magento Deploy Settings Those commands above for setup permission and ownership for all folders of project with some specific for pub/static/ and var/ folder. Capistrano using the setfacl to do that for SERVER_USER and SERVER_GROUP account.

D E P L O Y S E T T I N G s Composer Auth Credentials set :magento_auth_public_key, 'MAGENTO_USERNAME' set :magento_auth_private_key, 'MAGENTO_PASSWORD' This will execute that command below: composer config --global --auth http-basic.repo.magento.com MAGENTO_USERNAME MAGENTO_PASSWORD

D E P L O Y S E T T I N G s Magento Customize Tasks before 'magento:deploy:verify', 'magento2:copy_config' after 'magento:setup:static-content:deploy', 'magento2:add_adminer' after 'magento:maintenance:disable', 'magento2:restart_php_fpm' Note: - The 'copy_config' is customized task, see details in Q&A section.

Q U E S T I O N S s What the benefit of config.php.dist? Answer: It help you to controll what the modules you actually want to using them in your project, it will converted to config.php, so the your project must be have it in the app/etc folder. The customize task called 'copy_config' will help you to do all of this, see in my example repository for how to create this task.

Q U E S T I O N S s Why must to restart PHP FPM? Answer: We need to restart PHP FPM to flush cache of Zend Opcache - a native extension built-in PHP. Error: Don't know how to build task? Answer: Add require gem to the Capfile: # Load Magento deployment tasks require 'capistrano/magento2/deploy'

Q U E S T I O N S s Have any project for example? Answer: I created a Github repository, for example, I also using it for deploying my Magento 2 site, you can refer it at here: https://github.com/unetstudio/magento-2-capistrano- deploy

R E F E R E N C E S s https://github.com/capistrano/capistrano https://github.com/davidalger/capistrano-magento2 https://github.com/unetstudio/magento-2-capistrano- deploy https://github.com/bundler/bundler

A B O U T M E s Hi there, I'm Duc Dao. A web developer living in Hanoi, Vietnam. Currently, I'm working in SmartOSC corporation and love to share knowledge. Email: huuduc.uneti@gmail.com Website: http://newbie-dev.net

D U C D A O T H A N K Y O U !