• Servers and Tools

Use Custom Error Pages

From the class:  Getting Started with NGINX

A common requirement is to use custom error pages if something goes wrong. For example, if there's a server error or a maintenance page you want to show or something like that, you're probably not going to want to use the default that comes with nginx. So in order to do that, we can use a directive called Error Page. And Error Page takes as options the set of codes that we want to respond or direct to.

So the codes or this HTTP status codes. That could just be one or we could provide a few here. For example, let's say we want to send any code that comes back as 500, 502, or 504. These are HTTP status codes.

We're going to re-route those to the 50x or deliver the 50x .html file. So x being a variable for any of the 500 status codes. So now if an error happens in nginx or if any the locations return a status code of 500, 502, 504, all of those will send back this 50x file. And this is expected to be in the Public folder or in wherever root points to. In this case, it's pointing to the Public folder.

Another common example of an error page is if we want to show a maintenance page. So Evented Mind does this, for instance. And if I need to bring down the app servers for some reason, for example, I'm doing a big data migration or something where I just can't have the application up, then I'll show a temporary maintenance page.

And the 503 status code is the code for maintenance. And I'll send back the 503 .html file for that. We need to put semicolons at the end. Make sure you don't forget. And now that we've got the error page directives, we can try it out by going directly to these URLs. And that should work fine.

So first, let's come to the application itself and add the files into Public. And to save some time, I've pasted in HTML into 503 HTML file. It just says GET has a title of maintenance. And down in the body, it just says temporary maintenance.

And of course, you can make this fancier with a link that to your Twitter account or something like that to give users a place to go while you're working on the site. And in 50x in HTML, I just pasted in some code here as well. The body of the HTML just says, oh no. So not a very useful error page. You probably want to leave your email address or something like that.

But we'll just use this for demonstration purposes. And now we should be able to get to these files directly. Let's just test that out first.

And we'll deploy the result by pushing to deploy. And I should, without actually even restarting nginx since I've just added two new files to the public directory, they should be served automatically. So I can say CURL and then just give the 50x .html.

And we should get back this error page that we just created. And it looks like that's working correctly. Just simply by putting it into that public directory. Let's try the same thing for the 503 for our maintenance page.

And it looks like that's working as well. So now we've got both of these file serving correctly. The error page directive just says that if nginx gets a 50x something, 503 or 50x, automatically serve up one of these pages, 503 or 50x .html. And the nice thing about this architecture is that these files are coming from our application. So if we want to change this file, we can just push up a new version of our app and nginx will find of the new 503 files or 50x files automatically.

To try this out inside of the location block, what I can do is just return an HTTP status code. When the return directive gets executed, the rest of these statements don't matter. So we can right at the very top say return 503. And remember, 503 is a maintenance status code.

So this gives you a little sneak preview about how we can show a maintenance page. So I'm just going to return it on every request to the app location. And that should render out our 503 page down below.

So let's go ahead and restart the nginx server. And I'll make a request. And it looks like the maintenance page is showing correctly. So it sends back this 503 code, service temporarily unavailable. And here's our custom maintenance page that we created earlier.