staempfli/magento2-deployment-tool dev-master

Staempfli AG Magento2 Deployment Tool

Type

library

License

GPL-3.0

Requires
Requires (dev)

None

Suggests

None

Provides

None

Conflicts

None

Replaces

None

DEPRECATED

This tool has been deprecated in favor of magento2-deployer-plus. Although this repository will be kept and the tool works up to Magento 2.2.3, we will no longer add updates. Further developments will be done on the new tool magento2-deployer-plus.

If you were using this tool, we encourage you to migrate to the new one. New tool is an improved version of this one using deployer. New tool supports Magento versions <= 2.1.

You can find all information about the new tool in his repository:

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

Workflow:

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

Demos

  • Deploying git repo

Magento2 deploy from git

  • Deploying .tar archive

Magento2 deploy from tar

Installation

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
    

Setup

  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

Usage

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

Properties

You can customise properties according to your needs:

On the Server:

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

On the Project:

  • {{PROJECT_ROOT}}/config/project.properties
  • 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/project.properties 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
  • 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

      shared/magento/app/etc/env.php=>{{MAGENTO_DIR}}/app/etc/env.php
      shared/magento/pub/media=>{{MAGENTO_DIR}}/pub/media
      shared/magento/var/log=>{{MAGENTO_DIR}}/var/log
    
    • Note that you must replace {{MAGENTO_DIR}} with your magento dir or . if same as root project.

Scripts

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

cp deployment-settings/scripts/release-after.sh.dist deployment-settings/scripts/release-after.sh
vim deployment-settings/scripts/release-after.sh

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=
command.build.project.artifact=mkdir -p ${release.target} && tar -xzf ${downloads.target}.tar.gz -C ${release.target}

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 ${downloads.target}.tar.gz

NOTE ${} variables are automatically replaced during deployment.

Tips:

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/project.properties:

      vim deployment-settings/project.properties
      release.version=develop
      skipDatabaseBackup=1
    

Troubleshooting

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/project.properties
    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=${release.target}/${magento.dir} setup:static-content:deploy de_CH
    4. The result will be something like in this example:

       static-content.languages=en_US
       command.static-content.deploy.options=--exclude-theme Magento/luma --exclude-theme Magento/blank && ${bin.n98-magerun2} --root-dir=${release.target}/${magento.dir} setup:static-content:deploy de_CH --exclude-theme Magento/luma --exclude-theme Magento/blank && ${bin.n98-magerun2} --root-dir=${release.target}/${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

Prerequisites

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

ChangeLog

CHANGELOG.md

Developers

Licence

GNU General Public License, version 3 (GPLv3)

(c) 2016 Staempfli AG