Network

Maintenance mode and error pages

An app can be put in maintenance, showing visitors a page while chosen addresses still reach it, and can have a page of its own shown when it's down.

Using them

The app's Settings tab (Maintenance and error pages), the CLI, or PUT /api/apps/{id}/pages:

stackd apps maintenance web on --allow 203.0.113.7,10.0.0.0/8
stackd apps maintenance web off
{
  "maintenance": true,
  "maintenance_html": "<h1>Back at 14:00</h1>",
  "maintenance_allow": ["203.0.113.7"],
  "error_html": "<h1>Something broke; we're on it</h1>"
}
  • Maintenance: every request to the app's domains gets the maintenance page (stackd's own "Down for maintenance" when maintenance_html is empty) with 503 and Retry-After: 60, so search engines wait rather than drop the pages; requests from maintenance_allow reach the app as usual, to check it before opening it again. ACME challenges still get through.
  • Error page: the app's 502, 503 and 504, and the proxy's own when no replica answers, are replaced by error_html, status kept. WebSockets and event streams are left alone. An app that answers 503 on purpose gets its page replaced too.

Pages are up to 256 KiB of HTML: inline what they need, or load it from elsewhere.

Changes apply on every server within seconds, with no deploy, and work while the app is down or its replicas are restarting, whether the firewall is on or off.