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:

• 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 – Run upgrades if needed
  • magento:maintenance:disable – Disables maintenance mode
• 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 – Run upgrades if needed
• 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

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.

'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

[

]

static_deploy_options

Source

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

split_static_deployment

Source

Deploy frontend and adminhtml together as default

false

static_content_locales_backend

Source

Use the default languages for the backend as default

'{{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

['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');

'1'

content_version

Source

return time();

magento_dir

Source

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

'.'

shared_files

Source

Overrides shared_files from recipe/deploy/shared.php.

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

shared_dirs

Source

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

Source

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

Source

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

Source

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

magento_version

Source

// 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

:::info Autogenerated The value of this configuration is autogenerated on access. :::

database_upgrade_needed

Source

:::info Autogenerated The value of this configuration is autogenerated on access. :::

full_upgrade_needed

Source

//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

:::info Autogenerated The value of this configuration is autogenerated on access. :::

enable_zerodowntime

Source

Deploy without setting maintenance mode if possible

true

artifact_file

Source

Artifact deployment section The file the artifact is saved to

'artifact.tar.gz'

artifact_dir

Source

The directory the artifact is saved in

'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

'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

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"

null

artifact_path

Source

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

Source

The location of the tar command. On MacOS you should have installed gtar, as it supports the required settings :::info 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 {#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 {#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 {#magento-deploy-assets-adminhtml}

Source

Deploys assets for backend only.

magento:deploy:assets:frontend {#magento-deploy-assets-frontend}

Source

Deploys assets for frontend only.

magento:sync:content_version {#magento-sync-content_version}

Source

Syncs content version.

magento:maintenance:enable {#magento-maintenance-enable}

Source

Enables maintenance mode.

magento:maintenance:disable {#magento-maintenance-disable}

Source

Disables maintenance mode.

magento:maintenance:enable-if-needed {#magento-maintenance-enable-if-needed}

Source

Set maintenance mode if needed.

magento:config:import {#magento-config-import}

Source

Config Import.

magento:upgrade:db {#magento-upgrade-db}

Source

Upgrades magento database.

magento:upgrade {#magento-upgrade}

Source

Run upgrades if needed.

magento:cache:flush {#magento-cache-flush}

Source

Flushes Magento Cache.

deploy:magento {#deploy-magento}

Source

Magento2 deployment operations.

This task is group task which contains next tasks:

• magento:build
• magento:maintenance:enable-if-needed
• magento:config:import
• magento:upgrade
• magento:maintenance:disable

magento:build {#magento-build}

Source

Magento2 build operations.

This task is group task which contains next tasks:

• magento:compile
• magento:deploy:assets

deploy {#deploy}

Source

Deploys your project.

This task is group task which contains next tasks:

• deploy:prepare
• deploy:vendors
• deploy:clear_paths
• deploy:magento
• deploy:publish

artifact:package {#artifact-package}

Source

Packages all relevant files in an artifact.

tasks section

artifact:upload {#artifact-upload}

Source

Uploads artifact in release folder for extraction.

artifact:extract {#artifact-extract}

Source

Extracts artifact in release path.

build:remove-generated {#build-remove-generated}

Source

Clears generated files prior to building.

build:prepare {#build-prepare}

Source

Prepare local artifact build.

artifact:build {#artifact-build}

Source

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 {#deploy-additional-shared}

Source

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

magento:set_cache_prefix {#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 {#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 {#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 {#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 {#artifact-prepare}

Source

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 {#artifact-finish}

Source

Executes the tasks after artifact is released.

This task is group task which contains next tasks:

• magento:cache:flush
• cachetool:clear:opcache
• deploy:cleanup
• deploy:unlock
• deploy:success

artifact:deploy {#artifact-deploy}

Source

Actually releases the artifact deployment.

This task is group task which contains next tasks:

• artifact:prepare
• magento:maintenance:enable-if-needed
• magento:config:import
• magento:upgrade
• magento:maintenance:disable
• deploy:symlink
• artifact:finish