Maintenance Mode
Maintenance mode puts your app on pause: every visitor gets a “down for maintenance” answer with the HTTP status 503 Service Unavailable, while you run a risky migration, restore a backup or fix something urgent. One command turns it on, one turns it off:
node strut downnode strut upYou’d use it during a deploy that changes the database in a way the running code can’t handle, or when something is broken and you’d rather show a clean page than errors.
The smallest example
Section titled “The smallest example”Put the app in maintenance mode:
node strut downWhat you’ll see:
✔ The application is now in maintenance mode.Now every request answers 503:
curl -i http://localhost:3000/api/postsHTTP/1.1 503 Service Unavailablecontent-type: application/problem+json
{"type":"https://strutvane.dev/problems/maintenance","title":"Service unavailable","status":503,"code":"maintenance","detail":"The application is down for maintenance. Please try again soon."}A browser gets the same answer as a small HTML page. Bring the app back:
node strut up ✔ The application is now live.(Run up when the app isn’t down and it says · The application was not in maintenance mode.)
How it works
Section titled “How it works”down writes a small state file, storage/framework/down. Every running process of your app checks it on each request (it notices the change at once, with no restart), and up deletes it.
| Request | Answer |
|---|---|
| A page in the browser | 503, a small HTML page (or your own, see --render) |
An API call (/api/…, or Accept: application/json) |
503 problem+json with code maintenance |
The health route /up |
Still 200 {"status":"ok"}, so your load balancer doesn’t think the server crashed |
Someone with the bypass cookie (see --secret) |
The real app, as usual |
| A host name you don’t serve | Still refused first by the trusted-host check (400) |
The check runs before routing, middleware and your controllers, so no code of yours runs for a blocked request. That’s the point: a half-finished migration can’t be hit by a visitor.
Fail closed: if the state file is damaged or unreadable, the app stays down with the plain 503, rather than guessing it should be up.
Every option
Section titled “Every option”| Option | What it does | Example |
|---|---|---|
--secret=<value> |
Visiting /<value> sets a cookie that lets you use the app while it’s down. 8 to 128 letters, digits, - or _ |
--secret=team-preview-2026 |
--with-secret |
Like --secret, but Strutvane makes up a strong random secret and prints the link once |
--with-secret |
--retry=<seconds> |
Adds a Retry-After header, so clients and crawlers know when to come back |
--retry=60 |
--refresh=<seconds> |
Adds a Refresh header: browsers reload the page after that many seconds |
--refresh=15 |
--render=<file> |
Shows your own HTML page from resources/views/ instead of the default |
--render=maintenance.html |
--redirect=<path> |
Sends every visitor to one path of your own site instead | --redirect=/status |
Let yourself in: --with-secret and --secret
Section titled “Let yourself in: --with-secret and --secret”You often want to check that everything works before everyone else gets back in:
node strut down --with-secretWhat you’ll see:
✔ The application is now in maintenance mode. · Bypass it by visiting http://localhost:3000/3sJ0q8yVx2kWm7Pz9aBcDeFgHiJkLmNo (shown once; the secret is not stored).Open that link once. It sets a bypass cookie (strutvane_maintenance, valid for 12 hours, HttpOnly, SameSite=Lax, and Secure over HTTPS) and sends you to the home page. From then on, your browser sees the real app while everyone else sees the 503.
The secret itself is never stored: only a keyed hash of it (made with your APP_KEY) is in the state file, so reading the server’s files doesn’t reveal the link.
Prefer a secret you can type? Choose it yourself:
node strut down --secret=team-preview-2026Then visit http://localhost:3000/team-preview-2026. Anyone who knows it can get in, so --with-secret is the safer choice.
Tell clients when to come back: --retry
Section titled “Tell clients when to come back: --retry”node strut down --retry=120What you’ll see on every blocked request:
HTTP/1.1 503 Service Unavailableretry-after: 120Search engines read Retry-After and don’t drop your pages during a short outage.
Reload the page by itself: --refresh
Section titled “Reload the page by itself: --refresh”node strut down --refresh=30A visitor who leaves the page open sees it reload every 30 seconds, so they’re back in your app as soon as you run up, without pressing anything.
Your own page: --render
Section titled “Your own page: --render”Show a page that matches your brand instead of the default. Put a self-contained HTML file in resources/views/ (the one place Strutvane reads plain HTML pages from):
<!doctype html><html lang="en"> <head> <meta charset="utf-8"> <title>Back soon</title> <style>body { font: 18px system-ui; margin: 20vh auto; max-width: 32rem; }</style> </head> <body> <h1>We'll be right back</h1> <p>We're making a few improvements. Please try again in a few minutes.</p> </body></html>node strut down --render=maintenance.htmlThe page is read when you run down and stored in the state file, so it shows even if your app can’t load anything else (often the reason you’re in maintenance mode). Rules, for safety: it must be an .html file inside resources/views/ (no ../, no links pointing outside), at most 256 KiB. API calls still get the problem+json answer.
Send everyone somewhere else: --redirect
Section titled “Send everyone somewhere else: --redirect”node strut down --redirect=/statusEvery blocked request gets a 302 to /status (the page itself is still answered, so you can serve a status page from it). The target must be a path on your own site: https://other.example, //other.example and encoded tricks are refused, so down can never become an open redirect.
Typical: several options together
Section titled “Typical: several options together”node strut down --with-secret --retry=60 --refresh=15A safe deploy routine
Section titled “A safe deploy routine”Most deploys don’t need maintenance mode: new code and backwards-compatible migrations can go out while the app runs. Use it when a change can’t run side by side with the old code:
node strut down --with-secret --retry=60 # 1. pause the app, keep a way in for yourselfnode strut migrate --force # 2. change the database (--force: production asks otherwise)node strut optimize # 3. rebuild the production caches# 4. open the bypass link and check the app worksnode strut up # 5. everyone back inIf anything fails in steps 2 to 4, you’re still in maintenance mode: fix it, then run up. Nobody saw errors. See Optimization and Deployment.
Several processes and servers
Section titled “Several processes and servers”Every process that shares the project folder reads the same state file, so one down pauses all of them (the API, workers, a cluster of processes on one server). On several servers, run down and up on each, or put storage/framework/ on shared storage.
With Docker or without
Section titled “With Docker or without”| With Docker | Without Docker | |
|---|---|---|
Typing node strut down |
Forwarded into the app container for you |
Runs on your computer or server |
| What it pauses | Your app | Your app |
| What it does not do | Stop the containers: that’s node strut services:down |
— |
Common mistakes
Section titled “Common mistakes”I ran node strut down to stop Docker, and my app answers 503
Section titled “I ran node strut down to stop Docker, and my app answers 503”Why: down is maintenance mode, as in Laravel. Docker’s stop command is a different one.
Fix: bring the app back and stop the containers with the right command:
node strut upnode strut services:downI locked myself out
Section titled “I locked myself out”Why: you ran down without --secret or --with-secret, so there’s no bypass link.
Fix: run node strut up, then node strut down --with-secret and open the printed link.
“–secret must be 8 to 128 letters, digits, “-” or “_””
Section titled ““–secret must be 8 to 128 letters, digits, “-” or “_””” ✖ --secret must be 8 to 128 letters, digits, "-" or "_". → Or use --with-secret to generate a strong one.Fix: use a longer secret with only those characters, or --with-secret.
“–redirect must be a path on this site”
Section titled ““–redirect must be a path on this site”” ✖ --redirect must be a path on this site, such as /status (got "https://status.example.com"). → Absolute URLs, "//host" and encoded variants are refused, so maintenance mode can never send visitors elsewhere.Fix: use a path such as --redirect=/status, and link to the external status page from there.
“–render must name an .html file inside resources/views”
Section titled ““–render must name an .html file inside resources/views”” ✖ --render must name an .html file inside resources/views (got "../maintenance.html"). → Example: --render=maintenance.html for resources/views/maintenance.html.Fix: put the file in resources/views/ and pass only its name.
My load balancer marks the server as unhealthy during maintenance
Section titled “My load balancer marks the server as unhealthy during maintenance”Why: it checks a page that now answers 503, not the health route.
Fix: point the health check at /up, which keeps answering 200 in maintenance mode.
My custom page shows broken styles
Section titled “My custom page shows broken styles”Why: the page loads CSS or JavaScript from your app, which is blocked while it’s down. Fix: put the styles inline in the HTML file.
Next steps
Section titled “Next steps”- Optimization: the production caches to rebuild after a deploy.
- Deployment: building and running in production.
- CLI Reference: every
node strutcommand. - Docker:
services:upandservices:down.