Pro Tip: Redirecting to a Custom Nginx Maintenance Page

Here’s one I struggled with a bit while upgrading lincolnloop.com yesterday.

Scenario: You need to take your site offline and want to redirect all its traffic to a “down for maintenance” page. For search engine friendliness, that page should return a 503: Service Unavailable status code. Here’s the (not entirely intuitive) way to do that in Nginx:

server {
        listen      80;
        server_name mysite.com;
        root    /var/www/mysite.com/;

        location / {
            if (-f $document_root/maintenance.html) {
                return 503;
           }
            ... # the rest of your config goes here
         }

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

Now whenever you need to take your site offline, simply create the file maintenance.html in the $document_root (in our case, /var/www/mysite.com). If the file exists, Nginx will serve it with a 503 status code, if not, it will proceed as usual.

Comments

  • February 12, 2010 at 11:41 a.m. #
    Vitaly chimed in with:

    Thanks for the tip, I will be needing that soon.

  • August 2, 2010 at 12:39 a.m. #
    Nicolae Surdu responded:

    Thank you for the code, helped. I have a small improvement tho: the 503 should be sent only to peoples who are not you, so that you can test the code on the server prior to remove the maintenance status. Also, you may want to server a pagee outsite of your site’s document root folder :).

    geo $maintenance
    {
    default yes;
    34.72.156.110 no; #your ip
    }

    server{
    ...

    location / {
    if ($maintenance = yes)
    {
    return 503;
    }

    …

    error_page 503 502 @maintenance;

    location @maintenance
    {
    root /usr/local/www/www.mysite.ro/_maintenance;
    rewrite ^(.*)$ /index.html break;
    }
    }

  • August 21, 2010 at 7:11 p.m. #
    dudez commented:

    Thank you!

    My if (-f ..) is on the server level (outside of location) and for some reason when I did :

    if (-f $document_root/maintenance.html) {
    return 503;
    }

    it would return standard compiled in 503 error (which is ok), BUT mysteriously when I used custom 503 error page, as suggested by http://wiki.nginx.org/NginxHttpCoreModule#error_page, :

    error_page 503 /503.html;

    defined too on the server level, it would not return the contents of 503.html (or maintenance.html in your case) with the 503 error header, but just hit 10 redirect loops (error 500) and that was it. I tried a lot of variations (error_page before that if, error_page 503 = /503.html etc. etc.) and maybe 2 hours of trial/error.

Got something to say?





About Lincoln Loop | Our Team | Portfolio

This was written on February, 12 2010 and is filed in pro tip.

Our Products

Gondola
Gondola is a hosted CMS that gives designers a powerful and easy platform to create amazing geo-enabled Websites.
Trailmapping
Still in development, Trailmapping is a GPS enabled trail guide and trip logger.

Categories

Archives

Elsewhere

What we’ve been up to online

Interested in working with us?
Fill out the form below or contact us at:

PO Box 774441
Steamboat Springs, CO
80477

ph: 970.879.8810
fx:  970.367.8596
info@lincolnloop.com