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.

full_upgrade_needed​

Source

Default value
//Some conditions, such as new RabittMQ services require a full upgrade and are not detecet by setup:db:status
//TODO: Add checks, once implemented, for detecting necessary full upgrade process. See future RabbitMQ Check: https://github.com/magento/magento2/pull/39698
return false;

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:upgrade​

Source

Run upgrades if needed.

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', '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: