The simplest way to set-up a “we’ll be back shortly” page

If you’re going to have to stop your site for a maintenance or deploy break and care about your users (and SEO!), you should setup a custom 503 page. AskApache provides some documentation on this, but the examples require creating a PHP page. One of the commenters proposed a non-PHP version, but it’s complicated and didn’t work for me.

So, this is the simplest way to set-up a custom “we’ll be back shortly” error page in Apache 2 that also tells Googlebots to retry after 1 hour:

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

Read on for explanation and a more advanced example.

The above lines should be placed in you Apache’s site config file (e.g. /etc/apache2/vhosts.d/<your-site-name>_vhost.conf) somewhere under DocumentRoot directive. The first line sets a custom file for HTTP 503 status. The path you provide here is relative to DocumentRoot, so if you have:

DocumentRoot /var/sites/my_site/current/public
ErrorDocument 503 /503.html

then the file should be at /var/sites/my_site/current/public/503.html. Having a regular HTML means that you do not need anything except Apache itself to serve it. Inside it you can provide a message about the cause of the break and when you expect your site to be back up.

Next line (line #2 in first example) turns the RewriteEngine on, which is needed to process the following directives. Line #3 excludes from processing all the requests that go to our 503 page. Without it we would get an endless loop of redirections (which would not be endless in Apache, of course, but after exceeding the redirection limit would cause an error instead of producing the page).

Line #4 sets Retry-After header for bots, which is set here for 3600 seconds. If you expect your break to be much shorter, you can use a lower value. The last line sets a 503 response for all requests that made it up to here (i.e. not excluded by line #2).

Let the developers in

Often you need to allow some people (the developers or the client) to play with site even if it’s unavailable to the rest of the Internet. To do so, you can exclude them from getting the 503 page by entering their IPs:

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

The only thing new here is line #3, which excludes all requests coming from IP 1.2.3.4. You can use this directive as many times as you need.

Troubleshooting

If the above doesn’t work, first try following:

• Double-check the 503 file location.
• Assure that the owner of apache process can access and read this file.
• Make sure that you have mod_headers and mod_rewrite activated.