Skip to content

nginx Custom Maintenance Page without Redirects

For BreakBase, we use nginx as a reverse proxy to our app server. When we deploy updates, the upstream app server is temporarily offline. Rather than have nginx respond with the default “502 Bad Gateway” page, we replace it with our own maintenance page. Additionally, we also need to make sure our maintenance page does not redirect the user so their requested URI stays the same. That way when the upstream server is back online, a simple refresh will take the user to their originally requested page.

Below is the configuration for our maintenance page:

error_page 502 =200 @maintenance;
location @maintenance {
    root /path/to/maintenance;
    try_files $uri $uri/ /index.html =503;
}

There are a lot of things going on in this configuration. First off, we are using a named location with an error_page directive to “catch” the 502 error. Secondly, the =200 in this directive is used to set the response code to 200. This is done so browsers properly render the page as well as any CSS or images that are included.

Finally, we use the try_files directive in order to first try and serve the requested file (for CSS and images). If these files are not found, it will then try and serve an index.html file. If for some reason index.html is not available, we fallback to the default 503 error page which is more appropriate than the 502 page.