Maintenance mode
Table of Contents
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
- Enable maintenance mode only for specific client(s) (ie. to preview what it will look like)
- 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.