staempfli/magento2-deployment-tool 2.1

Staempfli AG Magento2 Deployment Tool





Requires (dev)










Magento 2 Deployment tool

Deployment tool for Magento 2 created with PHing. This tool builds a new project version into a separate directory and switches live version at the end.

Zero Downtime deployments using Magento >= 2.2 features


1. Get new Project version (i.e git clone, curl, ...)
2. Build Project (i.e composer install, untar, ...)
3. Symlinks to shared content in server
4. Generate Magento files and permissions (Skipped if `build.project.type=artifact`)
6. Set Maintenance (if needed)
7. Database backup (if needed)
8. Magento setup:upgrade (if needed)
9. Replace live version with new one
10. Unset maintenance
11. Clean up old releases and backups


  • Deploying git repo

Magento2 deploy from git

  • Deploying .tar archive

Magento2 deploy from tar


Global installation using composer is required.

  1. Composer require:

    composer global require "staempfli/magento2-deployment-tool":"~2.0"
  2. Check you global composer bin-dir configuration:

    composer global config -l | grep "bin-dir"
  3. Add path from previous step into your $PATH configuration:

  4. Open a new console tab and check that mg2-deployer tool is found

    which mg2-deployer


  1. File config.php is required to come within the project cloned.

    • You can follow the following documentation if you do not have your project configured like that yet:
  2. Create Database:

     CREATE DATABASE <database_name>;
     CREATE USER `<database_user>`@`<database_host>` IDENTIFIED BY "<user_password>";
     GRANT ALL ON <database_name>.* TO `<database_user>`@`<database_host>`;
  3. Run Setup: (this might take several minutes because of magento compilation)

    mg2-deployer setup
  4. At the end of the process you should get a folder structure similar to this:

  | - backups
  | - deployment-settings
  | - public_html (Symlink)
  | - releases
  | - tmp-downloads
  | - shared
    | - magento
        | - app (etc/env.php)
        | - pub
            | - media
        | - var
            | - log


Tool must be executed at the path where the the project will be deployed.

  • Deploy new releases:

    mg2-deployer release [-Drelease.version=<version_number>]
  • Other available commands:

    mg2-deployer -list
    Main targets:
    release               Options -> [skipCronInstall|skipDatabaseBackup|finishWithMaintenance]
    maintenance:set       Set maintenance window
    maintenance:unset     Replace maintenance window with a specific released version
    release:live:replace  Set a specific release as live version
    cache:clean:all       Clear all caches (Magento, OPcache, Varnish)

Custom Configuration


You can customise properties according to your needs:

On the Server:

  • deployment-settings/
  • Properties added in that file, overwrite default ones

On the Project:

  • {{PROJECT_ROOT}}/config/
  • If you want to share properties within your project, you can add them into that file.
  • Properties added here have the highest priority and will overwrite deployment-settings/ and default ones.

You can check all default properties that can be customised on:

Maintenance Window

You can edit the maintenance file with your own design:

vim deployment-settings/templates/maintenance/${magento.dir}/pub/index.php

Shared content & Symlinks

  • Static content that is only relevant on the server will be kept into the shared folder.
  • Symlinks are created automatically in the released project during every deployment.
  • You can add your custom symlinks by editing the file deployment-settings/shared.symlinks

    • Note that you must replace {{MAGENTO_DIR}} with your magento dir or . if same as root project.


You can set custom scripts to run at the end of the release process on the following file:

cp deployment-settings/scripts/ deployment-settings/scripts/
vim deployment-settings/scripts/

Build project from Artifact

If you select build.project.type=artifact, these are the default properties to get and build the project files:

command.get.project.artifact= -p ${} && tar -xzf ${}.tar.gz -C ${}

This configuration expects the artifact to be available inside tmp-downloads with .tar.gz extension.

If you need to get the artifact from a different server, you can modify the property like that:

command.get.project.version=scp <user>@<server_domain>:<path>${release.version}.tar.gz ${}.tar.gz

NOTE ${} variables are automatically replaced during deployment.


Speed up deployment process on dev-servers:

  • Release most recent version of develop branch -Drelease.version=develop
  • Skip database backup step -DskipDatabaseBackup
  • You can even set these options by default on deployment-settings/

    vim deployment-settings/


Js translations missing (magento versions >=2.1.3 <2.2.1)

  • Problem: Known Magento issue when executing setup:static-content:deploy for several languages.

  • Github Issues:

  • Solution: Until that gets fixed in 2.2.1, the only workaround is to execute setup:static-content:deploy individually for each language. To run that automatically with mg2-deployer release, you need to edit the following:

    1. vim deployment-settings/
    2. Set only 1 language on static-content.languages:

      • static-content.languages=en_US
    3. Add the rest of your languages on command.static-content.deploy.options with following command for each language:

      • && ${bin.n98-magerun2} --root-dir=${}/${magento.dir} setup:static-content:deploy de_CH
    4. The result will be something like in this example:

      command.static-content.deploy.options=--exclude-theme Magento/luma --exclude-theme Magento/blank && ${bin.n98-magerun2} --root-dir=${}/${magento.dir} setup:static-content:deploy de_CH --exclude-theme Magento/luma --exclude-theme Magento/blank && ${bin.n98-magerun2} --root-dir=${}/${magento.dir} setup:static-content:deploy fr_FR --exclude-theme Magento/luma --exclude-theme Magento/blank

Compilation error

  • Solution: Increase php memory_limit configuration to 728M o 1024M

Static deploy error when setting a new template (if config propagation is not used)

  • Problems:
    • [LogicException] Unable to load theme by specified key: 'Template'
    • @variable is undefined in file
  • Reason: If a new template is set, running setup:upgrade is required before executing setup:static-content:deploy
  • Solution: Skip setup:static-content:deploy first time you deploy the new template. Do a release following these steps:

    1. mg2-deployer release -DfinishWithMaintenance -DskipStaticContentDeploy
    2. <latest_release>/<magento_bin> setup:static-content:deploy <language1> <language2> ...
    3. mg2-deployer maintenance:unset

    After that, future deployments will work without issues


  • PHP >= 7.0.8
  • MAGENTO >= 2.2.1 (for previous Magento versions, use staempfli/magento2-deployment-tool:^1.2)




GNU General Public License, version 3 (GPLv3)


(c) 2016 Staempfli AG