Setup an Nginx Maintenance Page

Nginx grows in popularity day by day. Its solid performance and ease of setup make it a perfect tool to proxy traffic to your backend. In this article I will describe how you can configure a maintenance page that will be shown automatically every time you re-deploy or possibly your backend goes belly up.

If you already have an Nginx installation you can jump straight here. Otherwise I will guide you into installing Nginx as well. As usual, I will describe the installation procedure for CentOS 7. You can use the same procedure for any Fedora base distro.

Install Nginx

yum -y install nginx

Recommended Folder Structure for Configuration Files

mkdir /etc/nginx/sites-available
mkdir /etc/nginx/sites-enabled

We create configuration files in the sites-available folder. We activate configurations by symlinking them in the sites-enabled folder.

vi /etc/nginx/sites-available/mydomain-com.conf
ln -s /etc/nginx/sites-available/mydomain-com.conf /etc/nginx/sites-enabled/mydomain-com.conf

I will describe the content of the mydomain-com.conf later on. For now we just add the following line in /etc/nginx/nginx.conf to instruct it to scan our site-enabled folder when launching up.

include /etc/nginx/sites-enabled/*.conf;

Proxy Pass and Maintenance Page

This is the content of our site specific configuration file.

server {
    listen       80;
    server_name  your-domain.com;

    # Proxy all requests to your backend
    location / {
        proxy_pass http://127.0.0.1:30080; 
    }

    # Serve static files for http://your-domain.com/offline/* requests
    location /offline/ { 
        root /var/www;
    }

    # redirect 404 server error pages to the static page /40x.html
    error_page  404              /404.html;
    location = /404.html {
        root   /var/www/errors;
    }

    # redirect 500 server error pages to the static page /50x.html
    error_page   500              /50x.html;
    location = /50x.html {
        root   /var/www/errors;
    }

    # Maintenance page. 
    # If your backend is not reached by proxy_pass 
    # the offline.html file you stored in /var/www/offline/ will be shown instead.
    error_page   501 502 503 504  /offline.html;
}

As you can see the trick is simple. Proxy all requests to your backend except those hitting the /offline URL.

When your backend is down, Nginx will receive a 503 Service Unavailable error for which you instruct Nginx to display the offline.html file stored in /var/www/offline.

That’s all folks!