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.

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 (Skipped if deploying `.tar`)
5. Set folder/files permissions
6. Set Maintenance
7. Database backup
8. Magento setup:upgrade
9. Replace live version with new one
10. Unset maintenance
11. Clean up old releases and backups

Demos

Deploying git repo

Deploying .tar archive

Installation

Global installation using composer is required.

Composer require:

composer global require "staempfli/magento2-deployment-tool":"dev-master"

Check you global composer bin-dir configuration:
```
composer global config -l | grep "bin-dir"
```
Add path from previous step into your $PATH configuration:
Open a new console tab and check that mg2-deployer tool is found
```
which mg2-deployer
```

Setup

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:
  - docs/setup/config-php.md

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>`;

Run Setup: (this might take several minutes because of magento compilation)
```
mg2-deployer setup
```
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 -> [keepMaintenanceSet|skipDatabaseBackup]
 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 all properties according to your needs:

Properties added in deployment-settings/project.properties have the highest priority and will overwrite default ones
You can check all default properties that can be customised on:
- build/config/default.properties

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

Advanced Configuration (for CI/CD env)

If you are smart, you probably have a CI/CD environment where you already build the project and create a tar archive. Then you probably want to skip Magento generation files (assets & compilation) during the deployment.

You can do that by setting this configuration in deployment-settings/project.properties:

magento.generate.files=0
command.get.project.version=scp <user>@<server_domain>:<path>${release.version}.tar.gz ${downloads.target}.tar.gz
command.build.project.version=tar -xzf ${downloads.target}.tar.gz -C ${release.target}

command.get.project.snapshot=${command.get.project.version}
command.build.project.snapshot=${command.build.project.version}

NOTE ${} variables are automatically replaced during deployment.

Tips:

Speed up deployment process on dev-servers:

Release most recent version of develop branch -Drelease.version=snapshot
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=snapshot
skipDatabaseBackup=1

Troubleshooting

Compilation error

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

Static deploy error when setting a new template

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. After that, future deployments will always work

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

Prerequisites

PHP >= 7.0.8
MAGENTO >= 2.1.1

Developers

Juan Alonso

Licence

GNU General Public License, version 3 (GPLv3)

arybitskiy / magento2-deployment-tool Goto Github PK