Serve a static maintenance page when the frontend is unreachable

[ssavutu]

When Nginx cannot complete the proxy to the active frontend slot — connection refused because no container is listening, or a read timeout — it fell through to the stock Nginx error page. That page says nothing useful, carries no cache directives, and looks like a broken server rather than a site that is coming back.

location / now falls back to an internal rewrite to a self-contained maintenance page.

Three choices that are load-bearing

It is a rewrite, not a redirect. Uptime checks follow redirects, so a 302 to a down page would land every monitor on a 200 and report the site healthy for the whole outage. The client sees 503 on the URL it actually asked for.

The page sends Cache-Control: no-store. Cloudflare pinning it at the edge would keep the site dark after the backend recovered — the same trap as the /wp-content/ 404 caching this file already documents, except it takes out every page at once instead of one image.

proxy_intercept_errors stays off, so this only catches an unreachable upstream. Turning it on would also replace error responses the frontend returns on purpose, hiding real application behaviour.

502 and 504 are normalised to 503 to pair with Retry-After; the original code is still in error.log, which is where it gets diagnosed anyway.

Verified behaviour

Tested against a dead upstream in a container, not just nginx -t:

Request	Result
GET / (upstream dead)	503 + maintenance page, Cache-Control: no-store, Retry-After: 60, X-Robots-Tag: noindex
GET /_down.html	404 — internal;, so it cannot be cached or indexed as a 200
GET /healthz	200 — Nginx liveness unaffected
GET /v1/health/db	502, stock error — API never receives an HTML body

Deployment note

Nothing in deploy.sh installs the HTML. It is copied during bootstrap next to the site config, as documented in deploy/README.md. Worth folding into the deploy script later so it cannot drift.

🤖 Generated with Claude Code