ScaleScaleScaleScale

Tips / Nginx


Create a Custom HTTP 503 Maintenance Page Using Nginx

The HTTP 503 error code is simply a temporary service not available maintenance error. The 503 error is used to let customers and visitors know that you are facing temporary technical problems.

This situation is common when you are out of service because your system is  overloaded or down for scheduled maintenance. Luckily, on Nginx, you can customize the 503 maintenance page pretty easily.

Create an HTTP 503 maintenance page 

Build a file called 503.html inside of your site’s document root:

 nano -w /var/www/yoursite.com/503.html

Then, paste this inside and edit the message as needed:

503 Service Temporarily Unavailable
We are running temporary maintenance on this server/network. 
We will be back online soon.

Configure Nginx to serve your new 503 page

Place this ‘if’ statement inside of your virtual host file for the site you want the 503 page to work on:

if (-f $document_root/503.html) {
                return 503;
           }
           error_page 503 @maintenance;
           location @maintenance {
                rewrite ^(.*)$ /503.html break;
           }

This is a simple ‘if’ condition. If a 503 error appears in the system, then Nginx will serve the 503.html page from inside your document root path.

Reload Nginx to apply changes:

service nginx reload

What if you want some visitors to see your real content?

If you want some visitors to see the real content, use the allow/deny filters. These will help you to identify your visitors and choose how to act depending on their IP address.

You can use the $remote_addr variable to force a check against the remote IP address, and then pass or block any access.

  if ($remote_addr != "x.x.x.x") {
                return 503;
           }
           error_page 503 @maintenance;
           location @maintenance {
                rewrite ^(.*)$ /503.html break;
           }

Of course, you must replace “x.x.x.x” with the actual IP address that you want to allow access.

Reload Nginx to apply changes:

service nginx reload

What if you want to remove the maintenance page?

If you ever need to remove the maintenance page, comment out the added code with # before the lines. Alternatively, simply delete it from your Nginx configuration. Finally, reload Nginx and your maintenance page will be gone.

Popular search terms:

  • https://www scalescale com/tips/nginx/custom-503-maintenance-page/#
  • nginx maintenance page
  • nginx return 503
  • create custom 503 file
profile

Esteban Borges

Linux Geek, Webperf Addict, Nginx Fan. CTO @Infranetworking

  • Is there another way to do this, without if statements? Or in server level?
    If is evil.. http://wiki.nginx.org/IfIsEvil
    There they say: “In some cases it’s also possible to move ifs to server level (where it’s safe as only other rewrite module directives are allowed within it).”