Creating a Custom Maintenance Page in Magento2

At some point, you’ve likely visited a website and were met with a generic “down for maintenance” message.  It’s not unusual, but it can be frustrating – and sometimes unsettling – for your customers.

In these situations, you want to reassure your customers that (a) the service interruption is temporary, and; (b) provide critical information –Including other avenues available to the customer, and an ETA on when the site will be back online).

When you put your site in “Maintenance Mode”, Magento provides simple message by default.
But your customers deserve better than a generic message – let’s create a custom Magento 2 Maintenance Page that adheres to your branding and addresses the unique needs of your clients.

In this article we will show you two methods for creating a custom maintenance page:

  • Option 1: Create a custom Magento error skin (This requires coding skills and some time to set up.  This method may not be suitable for those new to Magento)
  • Option 2: Use a pre-built module (We’ve created a simple module you can use to display the custom HTML for your maintenance page)

What is the Magento Maintenance Mode?

As per devdocs Magento uses maintenance mode to disable bootstrapping while maintaining your store. This could be either upgrading, reconfiguring or any other actions the developer is making on the production site, where before going public, changes needs to be tested first.

In most cases, it is highly advised to enable maintenance mode during the deployment process.
In the Cloud version of Magento, maintenance mode is automatically enabled during deployment.

Option 1:  Adjusting the Maintenance Page in Magento

All the changes we’ll be making will conform to Magento best practices. We won’t modify any core files, so during any update nothing should break or be overridden.

Before we start, you need to make sure you have production mode enabled. To do that, just simply run in your CLI:

$ bin/magento deploy:mode:set production

Magento will behave like your production environment, which in this case is what we would like to have happen. You can read more about modes here.

To trigger maintenance mode, simply enable it by running below command:

bin/magento maintenance:enable

$ bin/magento maintenance:enable

Now, when you try to visit your store, you should see default maintenance Magento message as previously shown in this article.

Now, open your favorite code editor and locate pub/errors directory:

There are number of files and directories under “default”. That’s the default skin used for all the various messages magento displays, including maintenance, errors,  etc. Unfortunately, errors theming isn’t as sophisticated as Magento theming, so we need to copy the entire default folder and rename it. Later we will use that name to tell Magento which directory it should use for rendering error pages.

Now, let’s edit design.xml file located in pub/errors directory and just replace “default” name between <skin> tags with your name as below. In my case it is “alpine”:

Now, let’s open 503.phtml located in your skin folder and change the  h1 heading to something else to ensure that our skin is working:

Now you can adjust the page to suit your needs.
As you probably noticed, 503.phtml doesn’t contain whole page structure.
By default, magento shares an error page skeleton for all the messages. If you would like to edit, for example, the header tags, you need to make changes in page.phtml file. This is also the place where favicons and styles are loaded. To edit styles, just edit the file located under css directory in your skin.

Beware that all the changes you will make to page.phtml will be shared among all the Magento error pages.

If the above sounds like too much hassle or time – or if you already have a custom maintenance page and just want to upload it, this next option is for you:

Option 2:  Install Alpine Maintenance module.


As mentioned previously, here’s a GitHub link to download the module created by Alpine.  Installation instructions and other documentation are also available at the link above.

Once the module is installed, create the HTML file containing your maintenance content.  Make sure your file is named “index.html” and upload it to the Magento pub/maintenance directory.

This is also the place where you can store all the additional resources such as styles or images.
But remember the path should start from root while linking them in html.
Make sure Alpine’s module is enabled. You can do that by running:

$ bin/magento module:enable Alpine_Maintenance

Refresh your cache, and you should see your customized page while maintenance mode is turned on. This is what it looks like on our site:

Hopefully this guide has been helpful to you.  If you have any questions about setting up a custom maintenance page – or any other questions about Magento, please contact Alpine.  We’d love to hear from you!



1 reply

Trackbacks & Pingbacks

  1. […] Creating a Custom Maintenance Page in Magento2 by Michal Zymela […]

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *