Skip to main content
Version: 8.x

How to Deploy a Magento 2 Project

require 'recipe/magento2.php';

Source

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:

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

The artifact:deploy command of Magento 2 consists of:

The magento2 recipe is based on the common recipe.

Configuration

static_content_locales

Source

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.

Default value
'en_US'

magento_themes

Source

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

Default value
[

]

static_deploy_options

Source

Static content deployment options, e.g. '--no-parent'

split_static_deployment

Source

Deploy frontend and adminhtml together as default

Default value
false

static_content_locales_backend

Source

Use the default languages for the backend as default

Default value
'{{static_content_locales}}'

magento_themes_backend

Source

backend themes to deploy. Only used if split_static_deployment=true This setting supports the same options/structure as magento_themes

Default value
['Magento/backend' => null]

static_content_jobs

Source

Configuration Also set the number of concurrent jobs to run. The default is 1 Update using: set('static_content_jobs', '1');

Default value
'1'

content_version

Source

Default value
return time();

magento_dir

Source

Magento directory relative to repository root. Use "." (default) if it is not located in a subdirectory

Default value
'.'

shared_files

Source

Overrides shared_files from recipe/deploy/shared.php.

Default value
[
'{{magento_dir}}/app/etc/env.php',
'{{magento_dir}}/var/.maintenance.ip',
]

shared_dirs

Source

Overrides shared_dirs from recipe/deploy/shared.php.

Default value
[
'{{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

Source

Overrides writable_dirs from recipe/deploy/writable.php.

Default value
[
'{{magento_dir}}/var',
'{{magento_dir}}/pub/static',
'{{magento_dir}}/pub/media',
'{{magento_dir}}/generated',
'{{magento_dir}}/var/page_cache',
]

clear_paths

Source

Overrides clear_paths from recipe/deploy/clear_paths.php.

Default value
[
'{{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

Source

Default value
'{{release_or_current_path}}/{{magento_dir}}/bin/magento'

magento_version

Source

Default value
// detect version
$versionOutput = run('{{bin/php}} {{bin/magento}} --version');
preg_match('/(\d+\.?)+(-p\d+)?$/', $versionOutput, $matches);
return $matches[0] ?? '2.0';

config_import_needed

Source

Autogenerated

The value of this configuration is autogenerated on access.

database_upgrade_needed

Source

Autogenerated

The value of this configuration is autogenerated on access.

enable_zerodowntime

Source

Deploy without setting maintenance mode if possible

Default value
true

artifact_file

Source

Artifact deployment section The file the artifact is saved to

Default value
'artifact.tar.gz'

artifact_dir

Source

The directory the artifact is saved in

Default value
'artifacts'

artifact_excludes_file

Source

Points to a file with a list of files to exclude from packaging. The format is as with the tar --exclude-from=[file] option

Default value
'artifacts/excludes'

build_from_repo

Source

If set to true, the artifact is built from a clean copy of the project repository instead of the current working directory

Default value
false

repository

Source

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"

Default value
null

artifact_path

Source

The relative path to the artifact file. If the directory does not exist, it will be created

Default value
if (!testLocally('[ -d {{artifact_dir}} ]')) {
runLocally('mkdir -p {{artifact_dir}}');
}
return get('artifact_dir') . '/' . get('artifact_file');

bin/tar

Source

The location of the tar command. On MacOS you should have installed gtar, as it supports the required settings

Autogenerated

The value of this configuration is autogenerated on access.

additional_shared_files

Source

Array of shared files that will be added to the default shared_files without overriding

additional_shared_dirs

Source

Array of shared directories that will be added to the default shared_dirs without overriding

Tasks

magento:compile

Source

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

Source

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

Source

Deploys assets for backend only.

magento:deploy:assets:frontend

Source

Deploys assets for frontend only.

magento:sync:content_version

Source

Syncs content version.

magento:maintenance:enable

Source

Enables maintenance mode.

magento:maintenance:disable

Source

Disables maintenance mode.

magento:maintenance:enable-if-needed

Source

Set maintenance mode if needed.

magento:config:import

Source

Config Import.

magento:upgrade:db

Source

Upgrades magento database.

magento:cache:flush

Source

Flushes Magento Cache.

deploy:magento

Source

Magento2 deployment operations.

This task is group task which contains next tasks:

magento:build

Source

Magento2 build operations.

This task is group task which contains next tasks:

deploy

Source

Deploys your project.

This task is group task which contains next tasks:

artifact:package

Source

Packages all relevant files in an artifact.

tasks section

artifact:upload

Source

Uploads artifact in release folder for extraction.

artifact:extract

Source

Extracts artifact in release path.

build:remove-generated

Source

Clears generated files prior to building.

build:prepare

Source

Prepare local artifact build.

artifact:build

Source

Builds an artifact.

This task is group task which contains next tasks:

deploy:additional-shared

Source

Adds additional files and dirs to the list of shared files and dirs.

magento:set_cache_prefix

Source

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

Source

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

Source

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

Source

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

Source

Prepares an artifact on the target server.

This task is group task which contains next tasks:

artifact:finish

Source

Executes the tasks after artifact is released.

This task is group task which contains next tasks:

artifact:deploy

Source

Actually releases the artifact deployment.

This task is group task which contains next tasks: