Last updated 12 September 2017
Table of Contents
If you’re deploying a large migration or need to disable access to your application for some length of time, you can use Heroku’s built in maintenance mode.
When maintenance mode is turned on, your application will serve a static maintenance page to all visitors, while still allowing you to run one-off dynos. By default, the maintenance mode page is unstyled. To learn how to customize your maintenance page, see Custom Error Pages. Also, when maintenance mode is turned on, the error code H80 will be returned in your logs.
Scheduler jobs can still run while your application is in maintenance mode. Be mindful if you have any jobs set to run.
Enable maintenance mode:
$ heroku maintenance:on Enabling maintenance mode for myapp... done
Disable maintenance mode:
$ heroku maintenance:off Disabling maintenance mode for myapp... done
At any time, you can check the maintenance status of an app:
$ heroku maintenance off
Maintenance mode and dynos
Dynos will continue to accrue billing hours while in maintenance mode. Enabling or disabling maintenance mode doesn’t alter running dynos. Web dynos will continue to run as before, but won’t receive HTTP requests because the requests are blocked by the routers. Dynos of other types, such as worker dynos, will continue to run and you can also run one-off dynos as usual while maintenance mode is enabled using
Setting a custom maintenance page
You can set a custom maintenance page with the following enviroment variable:
heroku config:set MAINTENANCE_PAGE_URL=//s3.amazonaws.com/<your_bucket>/your_maintenance_page.html
Please see this article for more information.
Maintenance mode behavior in Common Runtime and Private Spaces
If you scale your web dynos to zero, the behavior of Maintenance Mode will differ in Common Runtime and Private Spaces. In Common Runtime, the maintenance page will continue to be served because it is served by a shared routing cluster. In Private Spaces, the maintenance page cannot be served if you scale web dynos to zero because it is served by the routing proxy that resides on the same compute instances as the dynos.
It can be useful to scale dynos to zero during maintenance operations, for example, to prevent any database transactions from taking place. In Private Spaces, you can only scale non-web dynos to zero. If you want to suspend transactions on your web dynos, you will need to build a mechanism into your application to control this.
You can enter maintenance mode and scale worker dynos to zero like this:
$ heroku maintenance:on Enabling maintenance mode for myapp... done $ heroku ps:scale worker=0 Scaling worker processes... done, now running 0
If you scale down dynos after enabling maintenance mode, be sure to scale them back up before returning traffic to the app.