Using Deployer for Magento 2 deployment

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

For the best results, install your own up-to-date Deployer version on a Savvii staging account. We keep Deployer 6 pre-installed on our servers to maintain backward compatibility for existing PHP 7 sites. However, because Deployer 7 and up introduced significant syntax changes and requires PHP 8+, running your own modern instance prevents version conflicts. Your staging account can then deploy updates locally via SSH before pushing to the live hosting environment.

If you prefer to keep execution isolated, you can run Deployer from a dedicated user account, a management VM, or use a CI tool like GitHub Actions.

2.1. Installing Deployer

The following commands will add Deployer 8 to your account and allow you to use it with dep

# Move to the bin folder
cd ~/bin
# Check GitHub for the latest version and download it.
curl -LO https://deployer.org/releases/v8.0.5/deployer.phar
#verify the md5 hash, expected: e5858fa961ecd4641adf35c848ddabe8
md5sum deployer.phar 2>/dev/null || md5 deployer.phar
# Make deployer executable.
chmod +x ~/bin/deployer.phar
# Rename deployer to dep
mv ~/bin/deployer.phar ~/bin/dep
# Rescan $PATH
hash -r

After Deployer has been installed, you can check if it's working with the following commands:

# which should output /home/$USER/bin/dep
which dep
# To check your Deployer version
dep --version

3. Setting up Deployer

For now we assume you are on a server with Deployer 8 installed and a working dep command.

3.1. The working directory

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

mkdir  ~/deployer
cd  ~/deployer

3.2. Create Hosts.yaml

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:

hosts:
    [server].savvii.io:
        remote_user: [user]
        labels:
            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.

3.3. 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';
import('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');

4. 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 stage=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.