Introducing clearmage2. Your path to nearly zero downtime Magento 2 maintenance

Magento 2 is a monster framework which, by default, requires quite some downtime after upgrading/enabling/disabling modules.
Generated PHP code must be recompiled, deployed static assets should be regenerated.

To add insult to injury, any of those steps might fail, rendering your live website unusable.

Fear no more. The clearmage2 tool, available by subscription from the GetPageSpeed repository, can save you from all these troubles and help you beyond that.

The clearmage2 runs Magento 2 production mode tasks with reduced downtime and is even capable of upgrading your Magento to a safe security version, automatically.


Installing clearmage2

sudo yum -y install https://extras.getpagespeed.com/release-latest.rpm
sudo yum -y install clearmage2

Using clearmage2

clearmage2, when invoked without arguments, generates static files and compiles generated code
within a shadow directory as opposed to your live site. This greatly reduces downtime and
even prevents ruining your website by a bad module that fails code generation.

It automatically creates the shadow directory using rsync, and runs heavy slow Magento 2
production tasks inside it, then pushes the generated files back to live, on success.

You can provide extra switches like --upgrade, so you can efficiently upgrade modules with less
downtime and without breakage, because the extra tasks are running in a shadow directory.


cd /path/to/magento2

# simply compile code and assets in the shadow, apply them and clear all caches

# additionally run "composer update" in the shadow 
clearmage2 --upgrade 

# enable or disable some modules:
clearmage2 --enable Some_Module,Some_Other
clearmage2 --disable Some_Module,Some_Other

# install a composer package and enable its modules in one go:
clearmage2 --install swissup/social-login --enable Swissup_Core,Swissup_SocialCore,Swissup_SocialLogin

# upgrade Magento 2 to the very latest!
clearmage2 --dist-upgrade

# upgrade Magento 2 with latest security fixes if any
clearmage2 --safe-dist-upgrade


This switch allows you to upgrade to the latest version of Magento 2.

Be sure to make any required changes first prior to jumping between major releases, e.g. 2.1.x to 2.3.x.

Recommended initial commands

Fix up your Magento 2 from creating user sessions for bots by running:

clearmage2 --install flancer32/mage2_ext_bot_sess --enable Flancer32_BotSess

You can also improve the performance of AJAX requests in Magento by reducing session locking:

clearmage2 --install getpagespeed/magento2-session-unblocker --enable IntegerNet_SessionUnblocker

When to run clearmage2:

  • after updating or installing a module
  • after changing styles, PHP files, etc

But it’s best to enable and disable modules using clearmage2 for very little downtime!


clearmage2 --disable Magento_AdminAnalytics,Magento_Marketplace

This will:

  • auto-create shadow directory if none
  • disable the modules in the shadow
  • generate compiled code in the shadow
  • generate static files in the shadow
  • rsync back generated files and run setup:upgrade at live (minimal downtime!)

So clearmage2 does most of the very slow and time-consuming tasks in a shadow directory,
thus reducing potential overall downtime to a very few seconds.