Automatic Maintenance Page for Nginx+Django app

If you've used Django with Nginx, you are probably familiar with how to configure the Nginx process group to reverse proxy to a second Gunicorn or uWSGI Django process group.  (The proxy_pass Nginx parameter passes traffic through Nginx to Django.)

One benefit of this approach is that if your Django process crashes or if you are preforming an upgrade and take Django offline, Nginx can still be available to serve static content and offer some sort of "the system is down" message to users.  With just a few lines of configuration, Nginx can be set to automatically display a splash page in the above scenarios.

If the Django process running behind the reverse proxy becomes unavailable, a 502 error will be emitted by Nginx.  By default, that 502 will be returned to the browser as an ugly error message.  However, Nginx can be configured to catch that 502 error and respond with custom behavior.  Specifically, if a 502 is raised by Nginx, Nginx can check for a custom html error page document and serve up that document if it exists.  If that document does not exist, Nginx can just return the default ugly 502 error message.  The Nginx configuration below executes this described behavior.

This Nginx example is stripped down to just demonstrate the concept described.  It only shows the server section portion of the Nginx config.  This example assumes that you have created your custom error page at the following location: /sites/joejasinski/htdocs/50x.html.

server.conf
...

# reverse proxy boilerplate

upstream app_server {

    server unix:/sites/joejasinski/var/run/django.socket;

}

server {

    listen   443;

    server_name  joejasinski.com www.joejasinski.com;

    ...

    # if Django is unreachable, a 502 is raised...

    error_page 502 @502;

    location @502 {

      root   /sites/joejasinski/htdocs/;

      # try to load a file called 50x.html at the document root

      # or re-raise a generic 502 if no such file is present.

      try_files /50x.html =502;

   }

    # reverse proxy boilerplate for hosting the Django app 
    location / {

        try_files $uri @proxy_to_app;

    }

    # reverse proxy boilerplate for hosting the Django app
    location @proxy_to_app {
        ....
       proxy_pass http://app_server;
    }

}

It's worth mentioning that, by default, if your Django app raises a 502 error behind the reverse proxy, Nginx will not catch it and thus will not respond with the custom Nginx 502 page.  The Nginx 502 error page is only displayed for 502 errors that originate from Nginx; an unavailable reverse proxy application qualifies as such.

This behavior is desirable since Django has it's own error handler for handling 50x errors within the application; we want Nginx to display an error page when Django is down, but Django should handle all errors generated by itself.

Note: you can change this behavior to have Nginx handle any error generated by the reverse proxied application.  This can be done with the proxy_intercept_errors Nginx parameter.

Note: using a similar approach to the above, you can also create error Nginx-based error handlers for other error codes generated by Nginx.

In summary, this approach allows you to automatically show users a friendly error page if your Django process crashes or is down for maintenance.