Is there a way to have a Heroku error/maintenance url served directly without the iframe

Question

Heroku allows you to turn "maintenance mode" on for your applications, and also allows you to specify a custom url to be served during this period. I just tried this out and discovered that Heroku serves the custom url in an iframe. This wasn't quite what I was expecting.

We use Heroku to host an API service, and had planned on having the custom error/maintenance pages serve json data. We're hoping that there is a way to have the maintenance url served directly.

After searching SO, Quora, and the general "internets" I haven't seen any posts asking this question, so here I am posting on SO.

Below are posts that are related to my question, but don't address it directly.

Old posts before there was any customization: https://groups.google.com/forum/?fromgroups=#!topic/heroku/EJRtW1XrlpU

Post asking for custom javascript in the html rendering the iframe: https://groups.google.com/forum/?fromgroups=#!topic/heroku/Db0JEWmuz_w

Ambry

jumand, did you manage to find a way to accomplish this? I'm facing a similar problem right now. – Goldplate

Nope. :-/ But we haven't looked into it since then. We spoke to a customer account manager back then, and it didn't seem like it was on the roadmap. – Ambry

Here's a workaround: https://mcmap.net/q/1207319/-is-there-a-way-to-have-a-heroku-error-maintenance-url-served-directly-without-the-iframe. – Decima

Answer 1

There is no way to customize the error page(s) other than outlined here, which use an iFrame: https://devcenter.heroku.com/articles/error-pages#customize-pages

Esbjerg

Answer 2

As a workaround, you can program your Heroku app so that for every request it receives, it first (before doing anything else) checks for the mere existence of a specific environment variable, eg, called MAINTENANCE. If set, you immediately return your custom JSON response.

For example, add the following block of code at the beginning of your Rack app's call method. (For a Sinatra app, you could add it at the beginning of a before filter. For a Ruby on Rails app, you could implement this as Rack middleware.)

if ENV['MAINTENANCE']
  status = '503'
  headers = {'Content-Type' => 'application/json'}
  body = ['{"message":"The server is undergoing maintenance. Please try again later."}']
  return [status, headers, body]
end

Then, to turn on "maintenance mode," set your app's MAINTENANCE environment variable to any value your heart desires.

heroku config:set MAINTENANCE=1

To turn off "maintenance mode," simply unset your app's MAINTENANCE environment variable.

heroku config:unset MAINTENANCE

Voila! Makeshift maintenance mode for a JSON REST API app.

Decima

Just notice that this is not full replacement of native Heroku maintenance mode as it does not work during app restart/scaling. – Siffre