Handling Maintenance Periods with Apache HTTP Server Version 2.2

Update (July 3rd, 2010): A follow-up article, ‘Automating Maintenance Periods with Apache HTTP Server Version 2.2 and PHP 5.3’ is now available.

Whenever you are performing maintenance on your website, it is good practice to display an appropriate informational page to your vistors, both human and bot alike. For example, the Googlebot likes to know when your site is down for maintenance, so that it can return later.

A quick and easy way to achieve this is through the use of Apache’s mod_alias. Simply the line, Redirect 503 / to a .htaccess file or your Apache virtual host configuration file. This will cause Apache to respond with the HTTP 503 return code and display the default built‐in error document to human visitors.

To display a more friendly message to visitors, just add the line ErrorDocument 503 /errors/503.html to the relevant Apache configuration file and create the /errors/503.html HTML document in your virtual host’s root directory.

Hopefully, you’ve seen a potential issue with this simple technique: you, as the developer get the same error message too! This issue can be partly resolved by using mod_rewrite to conditionally return the 503 response code. We use a RewriteCond directive to stop requests coming from the developer’s IP address from being redirected. This technique is also described in a post at “require ‘brain’”.

RewriteEngine On
RewriteCond %{REMOTE_ADDR} !^x\.x\.x\.x$
RewriteCond %{REQUEST_URI} !^/errors/503.html$
RewriteRule .* - [R=503]

In the above snippet, substitute ‘x\.x\.x\.x’ with the developer’s IP address. You must replace all ‘.’s with ‘\.’s because ‘.’ is a special character in regular expressions.

For even better search engine bot handling, we can use mod_headers to add the Retry-After header by adding Header always set Retry-After "3600" after the mod_rewrite statements.

So, the complete code is as follows:

ErrorDocument 503 /errors/503.html
RewriteEngine On
RewriteCond %{REMOTE_ADDR} !^x\.x\.x\.x$
RewriteCond %{REQUEST_URI} !^/errors/503.html$
RewriteRule .* - [R=503]
Header always set Retry-After "3600"

If you have an administration area on your website, or a tools such as phpMyAdmin installed, you might like to exclude them too. Just append another RewriteCond after the second, such as:

RewriteCond %{REQUEST_URI} !^/phpMyAdmin

This article was written for the Apache HTTP Server Version 2.2. The guidance here may or may not work with earlier versions of the software.

Initial version: March 7th, 2010. Updated with link to follow-up article: July 3rd, 2010.