Creating and Using Maintenance Pages

Here we will describe various ways to create and use those "Down for maintenance" pages that you should use when performing server work.

This is intended for serving "static" maintenance pages. You could implement a solution within the Pylons web application itself, but such a scheme might break down when upgrading Pylons, its dependencies, or any libraries your own application depends on.

Apache with mod_rewrite

This method has been snarfed directly from Ruby on Rails' Capistrano system.

Setup

See this page for the original source of this piece.

Add the following to your httpd.conf file:

1
2
3
4
5
6

RewriteEngine On

# Check for maintenance file and redirect all requests
RewriteCond %{DOCUMENT_ROOT}/system/maintenance.html -f
RewriteCond %{SCRIPT_FILENAME} !maintenance.html
RewriteRule ^.*$ /system/maintenance.html [L]

Usage

Create the system directory in your site's !DocumentRoot, and create a placeholder maintenance page. Name it something obvious, like maintenance.html.tmpl.

To activate the page, just copy it to system/maintenance.html. All requests will be redirected to the maintenance page.

To de-activate the maintenance page, simply delete it.

Apache .htaccess files

If you are using a web hosting provider chances are that you can't modify httpd.conf. But many providers do allow you to use an apache .htaccess file, which acts as a per-user httpd.conf.

Setup

Copy the above code into your site's .htaccess file.

Usage

Same as the aforementioned httpd.conf method.

Alternative Usage

Create a custom .htaccess file for maintenance-mode, and copy it into place when you need it.

Other servers (lighthttpd)

Other servers do not have rewrite rules, or they can not rewrite urls based on the existance of a specific file (lighthttpd has this problem). In these cases it may be best to create two web server configuration files – one for normal operation, and one for maintenance-mode.

When you need to turn on maintenance-mode simply restart the server, specifying that is should use the alternative config file.

NOTE: If you are on a high-traffic site, and you don't want a performance hit (as a result of file-system lookups in both of the Apache methods listed above), then this option is probably the way to go.

Many thanks to everyone on the #pylons IRC channel for their suggestions and help.