A Better Heroku Maintenance Mode

Oct 6, 2016 | Product,

Heroku’s default maintenance page is, well, a bit boring. It looks more like an nginx error and less like a friendly notice. Of course, they allow you to customize and provide your own page, but who wants to spend time working on that?

A little blah, eh?

A little blah, eh?

Enter Wrenchmode: The beautiful, interactive, easy maintenance page you can set up in less than 5 minutes. Then you can just get your maintenance over with and get back to working on the important parts of your app.

Much nicer!

Much nicer!

The 3 Minute Rails Setup

Getting Wrenchmode running on your Heroku project (currently only Rails or NodeJS/Express) is lightning fast. Here’s how:

Install the Add-on

$ heroku addons:create wrenchmode:test

Update Your Gemfile

# Gemfile
gem 'wrenchmode-rack'

Update config/environments/production.rb

# config/environments/production.rb
config.middleware.insert_after ActionDispatch::RemoteIp, Wrenchmode::Rack

Redeploy to Heroku

$ git push heroku master

Go To Your Dashboard

$ heroku addons:open wrenchmode

Wrenchmode On
Give a title and description to the maintenance incident, and Wrenchmode On!

Add a title and description, and then Wrenchmode On!

Add a title and description, and then Wrenchmode On!

NodeJS or Vanilla Rack
If you’re not using Rails, the process is just as easy. See our docs for help.

Bonus: Style!

One of the main drivers behind Wrenchmode was to get you a maintenance page as quickly as possible with a minimum of fuss. That’s why they look great out of the box with zero styling required. But, if you want, you can choose a different background from our library of images. Find something that meshes with your overall branding theme, or just one that conveys the right message for the given maintenance incident.

Bonus: Whitelist!

Once your maintenance is complete, you probably want to double check a few things before you throw the doors wide open. For that, Wrenchmode allows whitelisting your own IP address so you can peek around while everyone else is kept out.

If you are using Rails and followed the instructions above, everything will just work. Otherwise, refer to our docs on Heroku IP addresses to make sure you can whitelist yourself.

Back to Real Work!

That’s it! Now you can get your maintenance done while your users patiently wait, and then get back to the actual important business of your app.

How it Works (…if you care)

You may be (and should be) a little skeptical about how Wrenchmode works. Is it DNS craziness? A weird proxy? No and no. In a nutshell, the Wrenchmode middleware checks periodically with the Wrenchmode server to see if the site should be in maintenance mode or not. This happens asynchronously and outside the main request thread, meaning it has zero performance impact on your actual application.

When you turn Wrenchmode on, the middleware turns each request into a redirect to your Wrenchmode maintenance page. Users wait here until the maintenance is done, at which point they’re automatically returned to your site.

One final note: As a basic principle, the middleware is designed to fail open, meaning that if something happens to the Wrenchmode server or things otherwise go haywire, the middleware will automatically turn off maintenance mode. In other words, if Wrenchmode stops working for any reason, your website won’t be held hostage in maintenance mode or otherwise impaired.