Custom Maintenance Pages

(Fri Jan 05, 2007) [/Rails] #

Capistrano makes it quick and easy to put up a temporary maintenance page while you're doing chores around your production Rails app. Hopefully users won't see that page for long, but even when they do it's a nice touch to customize the page a smidge.

The stock maintenance page template that Capistrano uses by default is good, but it's easy to set your app apart from the rest. Simply redefine the disable_web task in your deploy.rb file to render a custom template. Here's an example:

task :disable_web, :roles => :web do
  on_rollback { delete "#{shared_path}/system/maintenance.html" }
  
  maintenance = render("./app/views/layouts/maintenance.rhtml", 
                       :deadline => ENV['UNTIL'],
                       :reason => ENV['REASON'])
                       
  put maintenance, "#{shared_path}/system/maintenance.html", 
                   :mode => 0644
end

This task uses ERb to render your local maintenance.rhtml template, and transfers the result to the maintenance.html file on all remote hosts in the web role.

I tend to put the maintenance.rhtml template in the layouts directory because it's a full HTML file like the other layout files, not just a fragment of HTML. Here's an example maintenance.rhtml template, sans all the surrounding HTML:

<h1>
  We're currently down for <%= reason ? reason : "maintenance" %>
  as of <%= Time.now.strftime("%H:%M %Z") %>.
</h1>
<p>
  Sorry for the inconvenience. We'll be back 
  <%= deadline ? "by #{deadline}" : "shortly" %>.
  Please email us if you need to get in touch.
</p>

You'll also need to tell your web server to check for the static maintenance file and redirect all requests to it if the file exists. Here's an example for Apache:

RewriteCond %{DOCUMENT_ROOT}/system/maintenance.html -f
RewriteCond %{SCRIPT_FILENAME} !maintenance.html
RewriteRule ^.*$ /system/maintenance.html [L]

Then, when it's time for some app maintenance, you can put up your custom maintenance page by typing

cap disable_web