Using Magerun with deploy hooks to prepare environments

For a brief introduction of Magerun or how to install it, please see this Confluence page: Magerun.

The purpose of this article

The purpose of this article is to show you how to use Magerun (or Magerun 2 for Magento 2) scripts in your projects in conjunction with Aja hooks to automatically set Magento config during deployment. We will be using different config values for each environment while keeping with the DRY (Don’t Repeat Yourself) principle.


Before you add Magerun hooks you must understand how to add Magerun scripts to your project’s local repository. See this Confluence page: Using Magerun modules in your projects.

Summary of what happens during deployment

  1. Aja hook file executes correct Magerun script
  2. Correct config for environment is set
  3. Cache is cleared (you can add any Magerun command to your scripts)
  4. Output of Magerun is logged to $webRoot/var/log/n98-magerun.log.

The hook file

The hook file contains the script that actually triggers the Magerun scripts to be executed based on which environment is being deployed.

Example hook file

Magento 2

You can see an example of a working Magerun hook file for Aja deployment in this project: project_dalema:hooks/














# Execute environment configuration adjustments

echo `date` “#” ${AJA_TASK_USER} “#” ${AJA_BUILD_NUMBER} “#” ${AJA_BUILD_REVISION} >> ${AJA_WWWROOT_PATH}/var/log/n98-magerun.log

echo ‘Magerun EXECUTE: /usr/local/bin/n98-magerun2.phar –skip-root-check –root-dir=”‘${AJA_WWWROOT_PATH}‘” script:repo:run set-‘${AJA_ENVIRONMENT_NAME}‘-config’


export HOME=/tmp

n98-magerun2 –root-dir=“${AJA_WWWROOT_PATH}” script:repo:run set-${AJA_ENVIRONMENT_NAME}-config >> ${AJA_WWWROOT_PATH}/var/log/n98-magerun.log


echo ‘Magerun DONE’

Explanation of hook file

In line number 4 we simply echo a log entry to $webRoot/var/log/n98-magerun.log. The log entry contains:

  1. The time (`date`)
  2. Aja task user (${AJA_TASK_USER})
  3. Aja build number (${AJA_BUILD_NUMBER})
  4. Aja build revision (${AJA_BUILD_REVISION})

In line number 7 we ensure that the deploy environment has the HOME environment variable. Otherwise Magerun will exit with this exception:


Unable to get home-directory to obtain user-config-file.

In line 8 we execute a Magerun script with a couple features:

  1. Notice that we execute only “n98-magerun2“. This is not a binary but rather an alias to the Magerun binary that hosting should have added to all servers. It ensures that Magerun is run with the correct user.
  2. The script name is dynamic and based on Aja environment name. Eg: script:repo:run set-dev-config. (script:repo:run set-${AJA_ENVIRONMENT_NAME}-config)
  3. We log the output of Magerun command to $webRoot/var/log/n98-magerun.log.

Since the hook dynamically calls Magerun scripts named after the current environment, you need to make sure that each environment has a script.

Magento 1















# Execute environment configuration adjustments

#n98-magerun –root-dir=”${AJA_WWWROOT_PATH}” script:repo:run set-${AJA_ENVIRONMENT_NAME}-config

mkdir -p ${AJA_WWWROOT_PATH}/var/log

magerun_binary=`which n98-magerun.phar`

if [[ -x “$magerun_binary” ]]


    echo “Magerun command: $magerun_binary –skip-root-check –root-dir=${AJA_WWWROOT_PATH} script:repo:run set-${AJA_ENVIRONMENT_NAME}-config >> ${AJA_WWWROOT_PATH}/var/log/n98-magerun.log 2>&1”

    $magerun_binary –skip-root-check –root-dir=“${AJA_WWWROOT_PATH}” script:repo:run set-${AJA_ENVIRONMENT_NAME}-config >> ${AJA_WWWROOT_PATH}/var/log/n98-magerun.log 2>&1


    echo “Could not run Magerun”



The Magerun scripts

Example environment script


 Expand source

Notice that the top and bottom lines  references external scripts. This is to avoid repeating ourselves when setting similar config across environments.

Also notice that the script name is set-dev-config.magerun. This script will automatically be run when deploying to the Aja environment named “dev”. See the hook file above.

Example of external Magerun script that is being reused

Notice that in the set-dev-config.magerun file above there is a call to script:repo:run common-test-config. Below you see the content of that file.


 Expand source

Again, see examples of all files in the project_dalema repository.

Preparing environments manually

You can also prepare environments manually by logging on to you server and running Magerun manually. Here is an example for setting up the dev environment:

Running Magerun script manually on server

$ cd /mnt/www/$instanceNumber

$ n98-magerun2 script:repo:run set-dev-config

This is particularly useful if you use Server Portal to sync live database into your test environment.

Using Magerun modules in your projects

The purpose of this article

The purpose of this article is to describe what Magerun scripts are and how to create Magerun scripts that are specific to your project.

About Magerun scripts

Magerun is an extremely useful set of Command Line Interface tools that allows you to quickly perform tasks on your Magento projects – like cache flushing, configuration setting and etc. I have briefly mentioned some of them in the Magerun article. Magerun scripts allow you to automate these commands into script files that are located in script repositories. One very useful implementation of Magerun scripts is to automatically prepare your environment by setting all configuration needed for your environment with a single command.

For example; running this command:

$ n98-magerun2 script:repo:run dalema

… will product this output:

$ n98-magerun2 script:repo:run dalema

 Expand source

(The source code for above output can be found in the “Example Magerun script” section below.)

Script repositories

Magerun scripts must be located in one of these places:

  1. /usr/local/share/n98-magerun2/scripts
  2. ~/.n98-magerun2/scripts
  3. As module in your local project

The first two locations are described on the Use n98-magerun Script Repository page. Both locations are specific to your local machine and are well documented. The third option allows you to ensure that scripts are local to your project, but there is no good documentation available on it. The third option (“As module in your local project”) is the basis for the “How to create Magerun scripts local to your project” section below. You can also find a repository description by showing help for the repository command: n98-magerun2 script:repo:list -h.

How to list which scripts are available to you

$ n98-magerun2 script:repo:list

 Expand source

How to create Magerun scripts local to your project

The scripts must reside in a specific folder structure relative to your project root:

Folder tree







Remember to replace $moduleName with your module’s name and $scriptName with your script’s name. In this article I have been using the name “dalema”. Also notice the .yaml file. It is required and must have the following content:

$ cat lib/n98-magerun2/modules/dalema/n98-magerun2.yaml






    – %module%/scripts

Now that you have placed your files in a location local to your project, you can go ahead and commit them to your project’s repository. You can see an example in this repository: project_dalema.

Example Magerun script

$ cat ~/.n98-magerun2/scripts/dalema.magerun

 Expand source

Notice that I automatically set value for a lot of configuration options. This will allow me to pull a Magento database locally and then simply run this script once to completely prepare my local environment. In another article I will describe how to use scripts like this as part of your normal site deployment using Aja hooks. Once you have done that it is exceedingly easy to synchronize databases between environments using Server Portal.


What is Magerun?

From Magerun’s GitHub repository

“The n98 magerun cli tools provides some handy tools to work with Magento from command line.”

With Magerun you can very quickly perform tasks like:

  1. Change admin password
  2. Clean cache
  3. Get and set config
  4. Do database dumps
  5. Reindex
  6. Get info about site
  7. Run install scripts
  8. And much, much more

It is a time saver on almost any Magento projects and we commonly also use it in conjunction with deploy hooks to automatically prepare our environments during deployment.

How to install Magerun

  1. For Magento 1 go to this GitHub repository and follow the instructions
  2. For Magento 2 go to this GitHub repository and follow the instructions

How to install on servers

Magerun2 should already be part of Puppet for PHP 7 servers. I am not sure if this is also the case for PHP 5 servers. You can use this JIRA issue as reference if you need to ask hosting to install it for you:  HOST-6479729 – Puppet: Install Magerun2 on V445 The new status lozengens support for JIRA 6.2 or later. Otherwise we use the icon. RELEASED

Child pages