Using Friendly Maintenance Pages with Ruby on Rails

By February 9, 2016 No Comments

At some point in every Rails application’s life, you’ll need to perform some kind of maintenance or code update that will require taking your application offline for a short period of time. There are methods to achieve zero-downtime deployments, but sometimes it’s just easier to take your application offline for 5 minutes during a deployment. If you know that no-one is writing data into the database, then you don’t have to worry about synchronizing data or merging database backups back in when you’re deployment is finished. It just makes life simpler in cases when a few minutes of downtime is acceptable.

But, during this “dark period” when your application is offline, you should still give your users some notice of what is going on, and when they can expect the maintenance period to end.

Enter the turnout gem.

Quick-Start with Turnout

The turnout gem makes it easy to quickly put up a friendly maintenance page for your users, and block access to all routes at the same time (to prevent writes to your database).

The main benefits are:

  • Easy installation
  • Rake commands to turn maintenance mode on and off
  • Easily provide a reason for each downtime without editing the maintenance.html file
  • Allow certain IPs or IP ranges to bypass the maintenance page
  • Allow certain paths to be accessible during maintenance
  • Easily override the default maintenance.html file with your own


In your Gemfile add:

gem "turnout"

then run

bundle install


rake maintenance:start reason="We're updating our site, please check back in 5 minutes"

Visit your site in your browser and you should see a page like this:

Quick and easy!


rake maintenance:end

There’s lots more you can do with the turnout gem, like customizing the HTML, allowing certain IP addresses through, etc. I’d encourage you to visit the turnout GitHub page to learn more.

Web Application Startup Guide

A 30-page ebook that covers positioning, marketing, pricing, and building your startup product, plus more.

Leave a Reply