How do I create a custom error page for when Tomcat is down for maintenance?
Author: Deron Eriksson
Description: This tutorial describes how to have Apache display a custom error page when an application deployed to Tomcat is down.
Tutorial created using: Windows XP || Apache HTTP Server 2.2.21


Page:    1

In another tutorial, we saw how we could connect an ApacheSW Web Server to a TomcatSW servletW container using a proxy. As an example, in my http.conf Apache configuration file, here's a proxy so that requests to URL paths starting with /tutorials will be handled by the tutorials JavaSW web application running on Tomcat. Tomcat is using its standard port, 8080.

<IfModule proxy_http_module>
ProxyPass /tutorials http://localhost:8080/tutorials
ProxyPassReverse /tutorials http://localhost:8080/tutorials
</IfModule>

If Tomcat isn't running or if the "tutorials" application isn't available, Apache will display a default 503 Service Temporarily Unavailable error message.

Apache default 503 Service Temporarily Unavailable error message

A common requirement is to have Apache display a custom maintenance error page when Tomcat is down or when an application running in Tomcat is down. This is quite easy to do. All we need to do is add an ErrorDocument entry to our http.conf file. On the ErrorDocument line, we specify the error code, which in this case is a 503. After that, we can specify either a text message or the page to display. I'll specify to display the "maintenance-message.html" page, which I create in the Apache document root directory, which in my case is in my Apache2.2.21/htdocs folder.

# Some examples:
#ErrorDocument 500 "The server made a boo boo."
#ErrorDocument 404 /missing.html
#ErrorDocument 404 "/cgi-bin/missing_handler.pl"
#ErrorDocument 402 http://www.sequoia.com/subscription_info.html
#
ErrorDocument 503 /maintenance-message.html

Here's the contents of the maintenace-message.html file that I created.

<h2>Maintenance is being performed</h2>

<div>We will be back shortly.</div>

I'll restart my Apache Web Server since I updated the httpd.conf configuration file. Now, if I try to hit the "tutorials" application through Apache and Tomcat is down, we see the custom error page rather than the default 503 error page.

Custom Error Page displayed when Tomcat is down

One thing you may notice if you play around with this is that after the 503 error page is displayed and you've restarted Tomcat, there can be a fairly significant delay before the content is displayed even though Tomcat is up. This is due to the default retry interval. If we'd like to see content through Apache immediately after Tomcat is restarted, we can add a "retry=0" to our ProxyPass entry.

<IfModule proxy_http_module>
ProxyPass /tutorials http://localhost:8080/tutorials retry=0
ProxyPassReverse /tutorials http://localhost:8080/tutorials
</IfModule>
Page:    1