Go to maintenance mode with Nginx


Every web-resource goes to maintenance work once in awhile. It might be a site renovation or motion to new server, doesn’t matter. The main target is a provide an alert for users. Basically it’s html page, which shows a simple message about web-site inaccessibility. It has 503 HTTP code.

For web-server administrators it’s going to be easy task. There are bunch of options to solve this question. Now I’d like to share with you my one. We use Nginx in a role of web-server, thusI’ll dedicate this post with it.

1. Check ngx_http_geo_module

geo_module provides an opportunity to distinguish a list of ip-addresses without rules appliance. Originally it should be web-developers and checking persons. Also geo_module can check location of web-client. So you can open/close your site access from any country. But now this feature is not necessary for maintenance mode. Except the case you want to change any language version.

Every Nginx module can be checked with nginx -V shell command. For geo_module it will be easy to grep this word from output stream.

nginx -V | grep "geo"

2. Declare geo variable

Here you need to be attentive. Directive of geo_module cannot be set into server directive or anywhere else. Otherwise Nginx takes it as a syntax mistake and fails to reload. Would be better to leave it on the top of nginx inventory file.

Every change will be done in Nginx inventory file. By default it locates in /etc/nginx/sites-available directory. Check that your inventory included into nginx.conf at first. Check Syntax of geo_module variable is simple. Here we’ll put inaccessible points as “0” and accessible as “1”. Let’s set a bunch of addresses in a role of maintenance members. Probably it will be one private network and a couple of remote workers.

geo $maintenance {
     default        0; 1; 1;

3. Set an empty file

For persistent “maintenance mode” regulation we can exploit a simple method. Just put an empty file with specific name inside of root directory. For instance, there will be .maintenance file. Later in location / subdirective we will apply one rule with file existence.

Set a multiple condition for rewrite to maintenance

Originally Nginx syntax doesn’t support multiple if/else conditions. But it was hacked far away. At first choose a “server” directive of site you can turn into maintenance. Later type inside of root subdirective next conditions.

set $test  A; 
     if (-f $document_root/.maintenance) { 
       set $test  "${test}B"; 
     if ($maintenance = 0) { 
       set $test  "${test}C"; 
     if ($test = ABC) { 
       return 503;

This condition based on a variable value. Depends on true/false conditions variable $test acquires new value. If every condition is true – return 503 page. Variable $maintenance was got from geo_module directive.

4. Link your maintenance

After redirection rule we’ll proclaim a layout of 503 page. It does at the same server directive.

          error_page 503 @maintenance;
            location @maintenance {
                 rewrite ^(.*)$ /503.html break;

The html-page personally is a simple message. Here is an instance of maintenance page markup. Thanks to pitch-gist for example.

<!doctype html>
 <title>Site Maintenance</title>
   body { text-align: center; padding: 150px; }
   h1 { font-size: 50px; }
   body { font: 20px Helvetica, sans-serif; color: #333; }
   article { display: block; text-align: left; width: 650px; margin: 0 auto; }
   a { color: #dc8100; text-decoration: none; }
   a:hover { color: #333; text-decoration: none; }
     <h1>We&rsquo;ll be back soon!</h1>


Sorry for the inconvenience but we’re performing some maintenance at the moment. If you need to you can always  href="mailto:#">contact us, otherwise we’ll be back online shortly!



— The Team





Most likely you have 2 questions about this option.

    1) Why do we need to set error page, when we can insert html page into “multiple condition?

It’s a good tone rule. It’s important to specify indication of files which referred with HTML-code. Also you can simply change location of your file in one line and web-server will redirect to another page.

    2) Why should we use an empty file, when we can just check a 503 page existence?

Do you want to delete a 503 page after come back? And, if yes, why? It’s trivial to delete or move a file and recreate it, when you want to go to the maintenance again. Empty file in condition is a simple signal for server which calls a 503 regime.

5. Reload Nginx

systemctl restart nginx

All changes should be granted and customers redirection will work. But don’t forget to check your configuration syntax by

nginx -t

shell command. And that is all! Improve your frontend and backend without doubts and worries.

Maintenance motion is a helpful thing for web-resource reconstruction. Don’t forget to remove your linked file, when you’ll get ready to run your site.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s