Home > Support > HOWTO List > Web > Creating a maintenance page for your site

Web howtos

Creating a maintenance page for your site

Inspired by "bob's tech ramblings". Sometimes we just need a simple maintenance page that can be displayed on the site while backend changes or other sysadmin functions are being performed. There are a few ways you can do that. Some are described here.

Design a maintenance page

Taking a few minutes to design a maintenance or holding page now is a great idea. That way its there when you need it, rather than having to make one at the last minute when things go bang, Key things to consider

Keep the page simple, it may need to load quickly while the web server is stressed. Try to avoid loading your main site template or external css/javascript, that might be part of what you are fixing. And make the page easy to statically cache. Remember that the format needs to be suitable for the platforms accessing that as well, for example from a mobile device. An all in one html page is best, possibly plus your logo image.

Do include essential content, for example a basic apology for the service interruption. If appropriate include details on how to contact you or your company. Include an eta for when the site will be back online. And otherwise consider pointing to some material to keep visitors busy until things are sorted.

There are a number of great resources online with suggestions, examples, and comparisons of maintenance pages used by various companies.

Maintenance pages using Apache rewrites

Create a maintenance.html page and create or remove the maintenance.enable page as needed so that user will see the 503 error page if that is required. You would normally add this inside a sites document root.

Add the below snippet to apache or the .htaccess file as the first *page* rewrite for your site.


RewriteEngine On
RewriteCond %{REMOTE_ADDR} !AAA.BBB.CCC.DDD
RewriteCond %{DOCUMENT_ROOT}/maintenance.html -f
RewriteCond %{DOCUMENT_ROOT}/maintenance.enable -f
RewriteCond %{SCRIPT_FILENAME} !maintenance.html
RewriteRule ^.*$ /maintenance.html [R=503,L]
ErrorDocument 503 /maintenance.html

What this does is...

turn on the rewrite engine
don't match your workstation or office IP address. (An exclusion so you can see the actual site, optional)
make sure the maintenance page exists
check for the .enable file. This is how you turn the holding page on and off. So that a service restart is not needed
don't apply the rule when serving the maintenance page (avoids circular rewrites)
Then the rule itself...

Bob says you can also also added the following line to "help stupid web caches not keep on showing the error page after the site is back."

Header Set Cache-Control "max-age=0, no-store"

Note that you can put all of the above (the rewrite and the header directives) in the virtualhost configuration for a site, or in a .htaccess file, depending on how your site is configured both methods should work fine.

Maintenance pages using Nginx

There are a number of solutions for a similar result with Nginx. Try something like the following. Note this would require a 'service nginx reload' to make active. But then you just need to touch that file or remove it as needed.


server {
  listen      80;
  server_name mysite.com;
  root /var/www/mysite.com/;

  location / {
    if (-f $document_root/maintenance.enable) {
      return 503;
    }
    ... # the rest of your config goes here
  }
  error_page 503 @maintenance;
  location @maintenance {
     rewrite ^(.*)$ /maintenance.html break;
  }
}

Maintenance pages using Tomcat (or other Java/JSP services)

There are a couple of cases to cover for tomcat. The easy way is where you use our recommended setup with apache in front using mod_ajp or mod_jk2. Then its as easy as configuring a custom apache error document. If tomcat stops responding for whatever reason apache will serve that page instead.


ErrorDocument 503 /maintance.html

Maintenance pages using HAProxy

Create a simple maintenance page, and add a directive like the following to the relevant listen section of the main HAProxy configuration.

errorfile 503 /var/www/503maintance.html

A few other thoughts

You may want to disable logging on requests to the maintenance page. This is good for speed, and also helps when disk space on the server is full, See documentation for your service for ways you can do that.

Having a separate server with a mini maintenance site could be better in some cases. You can redirect traffic there in the unfortunate case where your main site is all the way gone.