Maintenance mode

Enabling maintenance mode for a domain is very straightforward. You just need to create a file called .maintenance.on within the root directory for the domain/subdomain/

Eg. /microcloud/domains/example.com/.maintenance.on

The site will then serve up the contents of maintenance.example.com (where example.com is your domain name) instead of the normal directory. It will load index.html only - and other resources are relative to this file (images/css/js).

You can also edit the ___maintenance/example.com.access.conf file and add the following to the top, followed by an Nginx reload

set $maintenance on;

Toggle maintenance mode by condition

You can control whether maintenance mode is enabled or not for specific IPs, or user-agent's by modifying the ___maintenance/example.com.access.conf configuration file.

This file will allow you to toggle the $maintenance variable - to either

1. Enable maintenance mode only for specific client(s) (ie. to preview what it will look like)
2. Disable maintenance mode for specific client(s) (but leave maintenance mode on for everyone else)

In ___maintenance/example.com.access.conf simply use conditional statements to set the $maintenance variable, using either

• $maintenance off;
• $maintenance on;

Here are some examples to toggle maintenance mode by IP, and URI and user-agent - however, you are not restricted to the use of any of these.

Toggle maintenance mode by IP

Replace 127.0.0.1 as necessary

if ($remote_addr ~ (127.0.0.1)) {
  set $maintenance off;
}

For multiple IPs, simply separate them via a pipe (this is standard perl regex format)

if ($remote_addr ~ (127.0.0.1|172.16.0.1|10.0.0.1|192.168.0.1)) {
  set $maintenance off;
}

Toggle maintenance mode by URI

You may still want certain URLs to work (for callbacks/integrations) despite maintenance mode being enabled for everything else

Eg. To enable the paypal and sagepay callback URIs to bypass maintenance mode

set $maintenance on;
if ($uri ~ ^/(index.php/)?(paypal|sgps)(.*)$) {
  set $maintenance off;
}

Toggle maintenance mode by User Agent

Or you could negate maintenance mode, by only enabling it for certain user agents.

set $maintenance off;
if ($http_user_agent ~ MSIE) {
  set $maintenance on;
}

Toggle maintenance mode by Query Parameter

Or if you want to use a passphrase in a query parameter (eg. during a Magento upgrade, where IP filtering alone wouldn't be suitable).

Eg. https://www.example.com/?maintenance=my_secret

set $maintenance on;
if ($args ~ "maintenance=my_secret") {
  set $maintenance off;
}

! Please note that maintenance mode only supports static HTML with no external resources. ! If allowing API requests, the servers own IP ranges must be permitted access (both internal and external).

This allows for Magento upgrades to take place where the maintenance.flag file is not a suitable option.