MageHost - Using Deployer for Magento 2 deployment

Disclaimer: MageHost has joined forces with Savvii. Therefore, these articles are only relevant to existing MageHost customers. For more information on this, visit www.savvii.com/en/magehost.  

Automated deployment and versioning (working with releases) can greatly improve your development flow. A lot of our customers use a CI (Continuous Integration) or a deployment tool for this. One of the more popular options is Deployer.

1. Preparation

1.1. Magento 2 up and running

Make sure you already have Magento 2 up and running on the server before starting to set up deployment. In the examples below we expect Magento to be installed in ~/magento2

If you are currently not yet using the ~/shared folder for files which are not included in the release you need to move at least app/etc/env.php and pub/media to this folder. Below is an example how to do this.

mkdir  -p  ~/shared/app/etc
mkdir  -p  ~/shared/pub
mv  ~/magento2/app/etc/env.php  ~/shared/app/etc/env.php
mv  ~/magento2/pub/media        ~/shared/pub/media
ln  -s   ~/shared/app/etc/env.php  ~/magento2/app/etc/env.php
ln  -sn  ~/shared/pub/media        ~/magento2/pub/media

1.2. Agent Forwarding

Deployer needs to be able to connect to the hosting to deploy to using SSH. Using a password is not a good option because Deployer would need to ask the password all the time. The same applies to the connection to GitHub. Agent Forwarding is by far the easiest way to make it all work.

1.3. Magento needs to be pushed to Git

You also need to have your Magento install pushed to Git, including the app/etc/config.php file.

Below is an example how to do this based on a fresh GitHub repository.

cd  ~/magento2
cp  /srv/magehost/TOOLS/magento2.gitignore  .gitignore
git  init
git  add  -A
git  commit  -a  -m "Changes on $VHOSTDOMAIN"
git  remote  add  origin  'git@github.com:[gitUsername]/[gitRepo].git'
git  push  -u  origin  master

Now you can begin setting up your deployment. Make sure you test this against a staging server first, as using it in production without any testing may cause your environment to break.

2. Choose where to run Deployer

The easiest method is to run Deployer from a Staging account on a MageHost server. All our servers have Deployer installed by default, you can use the dep command rightaway. The Staging account will connect to itself using SSH to deploy a new version. Later on it can also connect to the live hosting account.

If you prefer to keep things more separate, you could use a separate account or VM to run Deployer, or you can use a CI Tool like Travis or GitHub Actions. To install Deployer yourself, you can follow these instructions.

For now we assume you are on a server with a working dep command.

Create a directory where you will put your deployment scripts. We will work in that directory. Example:

mkdir  ~/deployer
cd  ~/deployer

3. Create hosts.yml

First of all, we need to make a yaml file called hosts.yaml. This file will contain all the information Deployer needs to connect to a server. You can view an example below:

[server].magehost.pro:
  user: [ssh_user]
  stage: staging
  deploy_path: $HOME
  port: 2222

The server name, user and port are the details Deployer will use to connect over SSH. The deploy_path should always be the same.

4. Create deploy.php

Next, we will create a PHP file called deploy.php, this file will contain our instructions for deployer.

First of all, we will include deployer, the default Magento 2 recipe and our hosts.yaml. The default deployer script needs some help understanding the setup. Below is an example on how to do this (replace the variables):

<?php
namespace Deployer;

require 'recipe/magento2.php';

inventory('hosts.yaml');

// pass the name of our application to have a better overview of what is running
set('application', 'Cool Webshop');

// set the repository where Deployer needs to pull from
set('repository', 'git@github.com:[gitUsername]/[gitRepo].git');

// make sure Deployer uses our own PHP version and not the global version
set('bin/php', '$HOME/bin/php');

// make sure Deployer uses composer with our own PHP version
// this can also be composer2.phar
set('bin/composer', '$HOME/bin/php /usr/local/bin/composer.phar');

// tag the release with datetime for an easy overview of when deployments happened
set('release_name', date('YmdHis'));

// set the Apache user to make sure Deployer deploys files with the right owner
// this is our vhost user
set('http_user', get('user'));

// since we have no root permissions, this should be changed to chmod
set('writable_mode', 'chmod');

// flush opcache after deployment to update symlinks
task('reload:php-fpm', function () {
  run('/bin/bash ~/bin/reload_php.sh');
});
after('deploy:magento', 'reload:php-fpm');

5. First Deployment

After the setup is done, we can do our first deployment. For the first time, it is advised to do this in debug mode:

cd  ~/deployer
dep  deploy  -vvv  staging

You may be asked to accept the SSH fingerprint of the remote server and to enter the passphrase of your SSH key.

When the deployment is successful, you can see your home dir contains the following directories.

• current -> a symlink to the latest release
• releases -> a folder containing all the releases
• shared -> a directory with everything that should not be changed with a new deployment

After this, make sure to thoroughly test new deployments and your installation.

For more information, you can always check the Deployer docs.

Advanced setups

Based on your needs (and your Magento 2 version), you might want a more advanced setup using artifacts. For this, you can find some inspiration in the third party maintained Deployer Plus repo.