Custom maintenance page on Nginx

Configuration

1. Create a custom maintenance page that you would like to display to your users.
2. Change your Nginx configuration to include the following:

include /etc/nginx/extra.d/maintenance.conf;


location / {
    # Adding the following "if" statement config under "location" directive
    if (-e /var/tmp/nginx/maintenance) {
        set $maintenance on;
    }
    if ($intra) {
        set $maintenance off;
    }
    if ($maintenance = on) {
        error_page 503 /maintenance.html;
        return 503;
    }
    ...
}
...

The dots in the above example are a placeholder for the rest of your configuration file and should be removed.

3. Edit maintenance.conf file under “/etc/nginx/extra.d/maintenance.conf”

set $maintenance off;

location = /maintenancfe.html {
    internal;
}

4. (optional) If you want to exclude some IP or IP range from hitting the maintenance page (e.g. for development), Edit your geo.conf /etc/nginx/conf.d/geo.conf

geo $intra {
    default            0;
    127.0.0.1          1;
    10.0.0.0/8         1;
    100.0.0.0/26        1;
}

5. Restart Nginx

$ nginx -t
$ sudo systemctl restart nginx

Switching in and out of maintenance mode

Switching the maintenance on and off is very easy, just by creating and deleting a faile.

Switch on maintenance mode

$ touch /var/tmp/nginx/maintenance

Switch off maintenance mode

$ rm /var/tmp/nginx/maintenance