How to Deploy a Magento 2 Project
require 'recipe/magento2.php';
Deployer is a free and open source deployment tool written in PHP. It helps you to deploy your Magento 2 application to a server. It is very easy to use and has a lot of features.
Three main features of Deployer are:
- Provisioning - provision your server for you.
- Zero downtime deployment - deploy your application without a downtime.
- Rollbacks - rollback your application to a previous version, if something goes wrong.
Additionally, Deployer has a lot of other features, like:
- Easy to use - Deployer is very easy to use. It has a simple and intuitive syntax.
- Fast - Deployer is very fast. It uses parallel connections to deploy your application.
- Secure - Deployer uses SSH to connect to your server.
- Supports all major PHP frameworks - Deployer supports all major PHP frameworks.
You can read more about Deployer in Getting Started.
The deploy task of Magento 2 consists of:
- deploy:prepare – Prepares a new release
- deploy:info – Displays info about deployment
- deploy:setup – Prepares host for deploy
- deploy:lock – Locks deploy
- deploy:release – Prepares release
- deploy:update_code – Updates code
- deploy:env – Configure .env file
- deploy:shared – Creates symlinks for shared files and dirs
- deploy:writable – Makes writable dirs
- deploy:vendors – Installs vendors
- deploy:clear_paths – Cleanup files and/or directories
- deploy:magento – Magento2 deployment operations
- magento:build – Magento2 build operations
- magento:compile – Compiles magento di
- magento:deploy:assets – Deploys assets
- magento:maintenance:enable-if-needed – Set maintenance mode if needed
- magento:config:import – Config Import
- magento:upgrade:db – Upgrades magento database
- magento:maintenance:disable – Disables maintenance mode
- magento:build – Magento2 build operations
- deploy:publish – Publishes the release
- deploy:symlink – Creates symlink to release
- deploy:unlock – Unlocks deploy
- deploy:cleanup – Cleanup old releases
- deploy:success – Deploys your project
In addition the Magento 2 recipe contains an artifact deployment. This is a two step process where you first execute
bin/dep artifact:build [options] [localhost]
to build an artifact, which then is deployed on a server with
bin/dep artifact:deploy [host]
The localhost
to build the artifact on has to be declared local, so either add
localhost()
->set('local', true);
to your deploy.php or
hosts:
localhost:
local: true
to your deploy yaml.
The artifact:build command of Magento 2 consists of: * build:prepare – Prepare local artifact build
- build:remove-generated – Clears generated files prior to building.
- deploy:vendors – Installs vendors
- magento:compile – Compiles magento di
- magento:deploy:assets – Deploys assets
- artifact:package – Packages all relevant files in an artifact.
The artifact:deploy command of Magento 2 consists of:
- artifact:prepare – Prepares an artifact on the target server
- deploy:info – Displays info about deployment
- deploy:setup – Prepares host for deploy
- deploy:lock – Locks deploy
- deploy:release – Prepares release
- artifact:upload – Uploads artifact in release folder for extraction.
- artifact:extract – Extracts artifact in release path.
- deploy:additional-shared – Adds additional files and dirs to the list of shared files and dirs
- deploy:shared – Creates symlinks for shared files and dirs
- deploy:writable – Makes writable dirs
- magento:maintenance:enable-if-needed – Set maintenance mode if needed
- magento:config:import – Config Import
- magento:upgrade:db – Upgrades magento database
- magento:maintenance:disable – Disables maintenance mode
- deploy:symlink – Creates symlink to release
- artifact:finish – Executes the tasks after artifact is released
- magento:cache:flush – Flushes Magento Cache
- cachetool:clear:opcache – Clears OPcode cache
- deploy:cleanup – Cleanup old releases
- deploy:unlock – Unlocks deploy
- deploy:success – Deploys your project
The magento2 recipe is based on the common recipe.
Configuration
static_content_locales
Configuration
By default setup:static-content:deploy uses en_US
.
To change that, simply put set('static_content_locales', 'en_US de_DE');
in you deployer script.
'en_US'
magento_themes
Configuration
You can also set the themes to run against. By default it'll deploy
all themes - add('magento_themes', ['Magento/luma', 'Magento/backend']);
If the themes are set as a simple list of strings, then all languages defined in static_content_locales are
compiled for the given themes.
Alternatively The themes can be defined as an associative array, where the key represents the theme name and
the key contains the languages for the compilation (for this specific theme)
Example:
set('magento_themes', ['Magento/luma']); - Will compile this theme with every language from static_content_locales
set('magento_themes', [
'Magento/luma' => null, - Will compile all languages from static_content_locales for Magento/luma
'Custom/theme' => 'en_US fr_FR' - Will compile only en_US and fr_FR for Custom/theme
'Custom/another' => 'static_content_locales it_IT' - Will compile all languages from static_content_locales + it_IT for Custom/another
]); - Will compile this theme with every language
[
]
static_deploy_options
Static content deployment options, e.g. '--no-parent'
split_static_deployment
Deploy frontend and adminhtml together as default
false
static_content_locales_backend
Use the default languages for the backend as default
'{{static_content_locales}}'
magento_themes_backend
backend themes to deploy. Only used if split_static_deployment=true This setting supports the same options/structure as magento_themes
['Magento/backend' => null]
static_content_jobs
Configuration
Also set the number of concurrent jobs to run. The default is 1
Update using: set('static_content_jobs', '1');
'1'
content_version
return time();
magento_dir
Magento directory relative to repository root. Use "." (default) if it is not located in a subdirectory
'.'
shared_files
Overrides shared_files from recipe/deploy/shared.php
.
[
'{{magento_dir}}/app/etc/env.php',
'{{magento_dir}}/var/.maintenance.ip',
]
shared_dirs
Overrides shared_dirs from recipe/deploy/shared.php
.
[
'{{magento_dir}}/var/composer_home',
'{{magento_dir}}/var/log',
'{{magento_dir}}/var/export',
'{{magento_dir}}/var/report',
'{{magento_dir}}/var/import',
'{{magento_dir}}/var/import_history',
'{{magento_dir}}/var/session',
'{{magento_dir}}/var/importexport',
'{{magento_dir}}/var/backups',
'{{magento_dir}}/var/tmp',
'{{magento_dir}}/pub/sitemap',
'{{magento_dir}}/pub/media',
'{{magento_dir}}/pub/static/_cache',
]
writable_dirs
Overrides writable_dirs from recipe/deploy/writable.php
.
[
'{{magento_dir}}/var',
'{{magento_dir}}/pub/static',
'{{magento_dir}}/pub/media',
'{{magento_dir}}/generated',
'{{magento_dir}}/var/page_cache',
]
clear_paths
Overrides clear_paths from recipe/deploy/clear_paths.php
.
[
'{{magento_dir}}/generated/*',
'{{magento_dir}}/pub/static/_cache/*',
'{{magento_dir}}/var/generation/*',
'{{magento_dir}}/var/cache/*',
'{{magento_dir}}/var/page_cache/*',
'{{magento_dir}}/var/view_preprocessed/*',
]
bin/magento
'{{release_or_current_path}}/{{magento_dir}}/bin/magento'
magento_version
// detect version
$versionOutput = run('{{bin/php}} {{bin/magento}} --version');
preg_match('/(\d+\.?)+(-p\d+)?$/', $versionOutput, $matches);
return $matches[0] ?? '2.0';
config_import_needed
The value of this configuration is autogenerated on access.
database_upgrade_needed
The value of this configuration is autogenerated on access.
enable_zerodowntime
Deploy without setting maintenance mode if possible
true
artifact_file
Artifact deployment section The file the artifact is saved to
'artifact.tar.gz'
artifact_dir
The directory the artifact is saved in
'artifacts'
artifact_excludes_file
Points to a file with a list of files to exclude from packaging.
The format is as with the tar --exclude-from=[file]
option
'artifacts/excludes'
build_from_repo
If set to true, the artifact is built from a clean copy of the project repository instead of the current working directory
false
repository
Overrides repository from recipe/common.php
.
Set this value if "build_from_repo" is set to true. The target to deploy must also be set with "--branch", "--tag" or "--revision"
null
artifact_path
The relative path to the artifact file. If the directory does not exist, it will be created
if (!testLocally('[ -d {{artifact_dir}} ]')) {
runLocally('mkdir -p {{artifact_dir}}');
}
return get('artifact_dir') . '/' . get('artifact_file');
bin/tar
The location of the tar command. On MacOS you should have installed gtar, as it supports the required settings
The value of this configuration is autogenerated on access.
additional_shared_files
Array of shared files that will be added to the default shared_files without overriding
additional_shared_dirs
Array of shared directories that will be added to the default shared_dirs without overriding
Tasks
magento:compile
Compiles magento di.
Tasks
To work correctly with artifact deployment, it is necessary to set the MAGE_MODE correctly in app/etc/config.php
e.g.
'MAGE_MODE' => 'production'
magento:deploy:assets
Deploys assets.
To work correctly with artifact deployment it is necessary to set system/dev/js
, system/dev/css
and system/dev/template
in app/etc/config.php
, e.g.:
'system' => [
'default' => [
'dev' => [
'js' => [
'merge_files' => '1',
'minify_files' => '1'
],
'css' => [
'merge_files' => '1',
'minify_files' => '1'
],
'template' => [
'minify_html' => '1'
]
]
]
magento:deploy:assets:adminhtml
Deploys assets for backend only.
magento:deploy:assets:frontend
Deploys assets for frontend only.
magento:sync:content_version
Syncs content version.
magento:maintenance:enable
Enables maintenance mode.
magento:maintenance:disable
Disables maintenance mode.
magento:maintenance:enable-if-needed
Set maintenance mode if needed.
magento:config:import
Config Import.
magento:upgrade:db
Upgrades magento database.
magento:cache:flush
Flushes Magento Cache.
deploy:magento
Magento2 deployment operations.
This task is group task which contains next tasks:
- magento:build
- magento:maintenance:enable-if-needed
- magento:config:import
- magento:upgrade:db
- magento:maintenance:disable
magento:build
Magento2 build operations.
This task is group task which contains next tasks:
deploy
Deploys your project.
This task is group task which contains next tasks:
artifact:package
Packages all relevant files in an artifact.
tasks section
artifact:upload
Uploads artifact in release folder for extraction.
artifact:extract
Extracts artifact in release path.
build:remove-generated
Clears generated files prior to building.
build:prepare
Prepare local artifact build.
artifact:build
Builds an artifact.
This task is group task which contains next tasks:
- build:prepare
- build:remove-generated
- deploy:vendors
- magento:compile
- magento:deploy:assets
- artifact:package
deploy:additional-shared
Adds additional files and dirs to the list of shared files and dirs.
magento:set_cache_prefix
Update cache id_prefix.
Update cache id_prefix on deploy so that you are compiling against a fresh cache Reference Issue: https://github.com/davidalger/capistrano-magento2/issues/151 To use this feature, add the following to your deployer scripts:
after('deploy:shared', 'magento:set_cache_prefix');
after('deploy:magento', 'magento:cleanup_cache_prefix');
magento:cleanup_cache_prefix
Cleanup cache id_prefix env files.
After successful deployment, move the tmp_env.php file to env.php ready for next deployment
magento:cron:stop
Remove cron from crontab and kill running cron jobs.
Remove cron from crontab and kill running cron jobs To use this feature, add the following to your deployer scripts:
after('magento:maintenance:enable-if-needed', 'magento:cron:stop');
magento:cron:install
Install cron in crontab.
Install cron in crontab To use this feature, add the following to your deployer scripts:
after('magento:upgrade:db', 'magento:cron:install');
artifact:prepare
Prepares an artifact on the target server.
This task is group task which contains next tasks:
- deploy:info
- deploy:setup
- deploy:lock
- deploy:release
- artifact:upload
- artifact:extract
- deploy:additional-shared
- deploy:shared
- deploy:writable
artifact:finish
Executes the tasks after artifact is released.
This task is group task which contains next tasks:
artifact:deploy
Actually releases the artifact deployment.
This task is group task which contains next tasks: