Maintenance mode

Maintenance mode puts a project's site behind a maintenance page with one click. Use it for the length of a risky change: a database migration, a big upgrade, a data fix you don't want users writing into halfway through. You don't need to edit nginx or SSH into anything.

Turning it on#

1. On the Projects page, click the maintenance button on the project.
2. Write a message for visitors, or leave it blank for a sensible default.
3. Optionally, set Expected back by. It's shown on the page in each visitor's own time zone.
4. Click Turn on maintenance.

The dialog shows a preview of the page before you turn it on. While maintenance is on, the project shows a Maintenance badge in the list.

The project needs a domain, because the page is served for that domain. A project reached only by IP and port has nothing to put a page in front of.

What visitors get#

• Every page shows the maintenance page, with HTTP status 503. That includes deep links, API calls and form submissions; POSTs get the same honest 503, not an error.
• Search engines treat it as temporary. A 503 with Retry-After tells them to come back later rather than index the maintenance page as your site. Retry-After is set from your "expected back" time, when you give one.
• Nothing is cached. The page is sent with Cache-Control: no-store, so no browser or proxy keeps showing it after you're back.

Checking the real site before you reopen it#

While maintenance is on, the dialog shows a link for your team. Opening it shows the real site in that browser for 12 hours, while everyone else still sees the maintenance page. That's how you check your change before bringing the site back.

Anyone with the link gets past the page, so share it only with the team. It changes every time maintenance is turned on, and editing the message doesn't change it.

Bringing the site back#

Open the dialog and click Bring … back. The page is removed and the site answers again immediately. The "expected back" time never switches maintenance off by itself; the site comes back when a person decides the change is done.

Did it actually work?#

After each change, the server asks for the site the way a visitor would and reports what it got:

What keeps working#

• Certificate renewals. Let's Encrypt challenges still reach the site, so a renewal that falls in the window doesn't fail.
• Your app. Nothing is stopped. The app keeps running behind the page, so you can deploy, run migrations from the terminal or a scheduled command, and check it through the team link.
• Deploys. Deploying, rolling back and promoting while in maintenance don't take the page down. Maintenance stays on until you turn it off.

Uptime alerts pause#

A site in maintenance is recorded as Maintenance in uptime checks, not as down, and raises no alerts. Downtime someone chose shouldn't wake anyone up. When you bring the site back, checks resume normally. An alert that was open from before maintenance closes once the site answers.

Limits#

• The domain can't be changed while maintenance is on. Turn it off first.
• The server must be online to turn maintenance on or off. The page is served by nginx on that server, so if the panel can't reach the server, the site stays as it is until the server reconnects.
• The message is plain text, up to 500 characters.
• The server needs an up-to-date agent. If the agent is too old, the dialog tells you to update it.

Who can use it#

Maintenance mode needs project.deploy, the same permission as deploying, since it takes the site offline for visitors. The bypass link is only shown to people with that permission. Every change is recorded in the audit log.

On a protected project, maintenance mode does not need approval. It's reversible, and it's what you reach for in the middle of an incident, where waiting for a second person is the wrong kind of friction.