Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,110 of 9,110 pages
About the help in other languages
All help pages

Maintenance mode and planned work

How to plan and announce work that takes an Exponential site offline, what customers and search engines see during maintenance mode, how to switch it on and off from the administration or a shell, and the safety rules…

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/businesses/reliability/maintenance-mode-and-planned-work.md

On this page

Maintenance mode and planned work

This page is for owners and managers who decide when the site may be offline, and for the administrator who takes it offline. It explains what customers and search engines see, how to plan and announce a window, how to switch it on and off, and the rules that keep a short window from becoming an outage. The complete guide is Maintenance mode: taking the site offline and bringing it back.

Setup, Maintenance: plan a maintenance window
Setup, Maintenance: plan a maintenance window

Contents

  1. Why a clean maintenance page matters
  2. What customers and search engines see
  3. Planning a window
  4. Switching it on and off
  5. Who still gets in
  6. Emergencies
  7. What maintenance mode does not stop
  8. Safety rules

Why a clean maintenance page matters

Some work needs the site offline for a while: an upgrade, a large data import, a database migration, a restore. Without maintenance mode, visitors meet errors and half-changed pages during that time. With it, they get a clear message and an expected time, and search engines are told to come back later instead of dropping your pages.

Maintenance mode is part of every installation. The installers use the same mechanism, "so a site that is being installed never serves a half-built page" (Maintenance mode feature).

What customers and search engines see

While maintenance is on, every page request gets one maintenance page with these headers (Maintenance mode guide, what it does):

HeaderMeaning
503 Service Unavailable"Temporarily unavailable", not "gone"
Retry-AfterSeconds until the expected end, or 120 when none is given
Cache-Control: no-store ...No cache, proxy or browser keeps the maintenance page after the window
X-Robots-Tag: noindexThe maintenance page itself is not indexed

"A 503 with Retry-After is the answer search engines understand as 'come back later': the pages keep their place in the index" (same section). Images, styles and scripts are still served.

The check runs first in the front controller, before the settings and the database, so the maintenance page "needs nothing that may be broken during the window: no template, no INI file, no database connection" (same section).

Planning a window

StepWhat to decide
TimingA quiet hour for your customers, never just before a sale or a newsletter send (Peak traffic planning)
DurationA realistic estimate plus margin; rehearse the work on a copy to know it
MessageWhat is happening and when the site is back, in customers' words: "We are upgrading the shop. Back at 06:00 UTC with the new checkout."
AnnouncementTell customers, members and staff in advance: a notice on the site, a newsletter line, social media
BackupA fresh backup before the window opens (Backups that restore)
CronjobsWhich scheduled jobs must not run during the work (Cronjobs and background jobs)
Who decidesWho may extend the window, and who may decide to roll back instead

Note

"Maintenance never ends by itself when the expected time passes" (Maintenance mode guide). The expected end is a promise to customers, not a timer. Your monitor should alert when a window overruns (Health checks and monitoring).

Switching it on and off

In the administration: Setup > Maintenance (/setup/maintenance). The form asks for an optional message, an optional expected duration (one click for 15 minutes to 4 hours), and who still gets in. A preview shows the real page, and a required confirmation guards the button Take the site offline. Bring the site back online ends it (Maintenance mode guide, in short).

From a shell (options checked against bin/php/maintenance.php):

php bin/php/maintenance.php on --message="Back at 06:00" --until=2h --allow-admin --allow-root-user
php bin/php/maintenance.php status --allow-root-user
php bin/php/maintenance.php off --allow-root-user

Without --allow-admin the administration is offline too (Maintenance mode guide, from the command line). --allow-root-user is only needed when running as root.

Every switch on and off is recorded in the audit trail as system.maintenance.change, and the page lists the latest eight (Maintenance mode guide, the audit).

Who still gets in

  • The administration: always reachable when maintenance is switched on from the page; from a shell only with --allow-admin.
  • Your own address: one tick on the page, so you can check your work while customers see the maintenance page.
  • Other addresses: for testers who must see the new site before everyone else. Each address is compared exactly; ranges are not supported (Maintenance mode guide, step 3).

Emergencies

When something is breaking pages in front of customers and you need a minute to look, the guide's emergency workflow is one command (Maintenance mode guide, an emergency):

php bin/php/maintenance.php on --message="We are fixing a problem. Back shortly." --allow-admin --allow-ip=<your address>

Fix, check from your address, then switch it off. A short, honest maintenance page is better for customers and search engines than a stream of errors. See Incident response for small teams.

If nothing else works, the state is one file: "Deleting the file ends maintenance: that is the way back in when nothing else works" (Maintenance mode guide). The file is var/maintenance.json.

What maintenance mode does not stop

  • Cronjobs run in a shell and keep running. "Stop the crontab yourself when a job must not run while you change the site" (Maintenance mode guide, cronjobs). Cronjob parts can also be paused from Setup > Cronjobs (Pausing cronjob parts).
  • Deploys (exp:velocity deploy) do not switch maintenance on or off; open the window yourself first.
  • A CDN or reverse proxy may still hold pages from before the window; purge it when content changed.
  • Several web servers: the state is a file in each server's var/ directory; switch it on and off on every server (Several web nodes).

Safety rules

From the guide's safety checklist, in business terms:

Before switching on:

  • To do: You can still reach the administration, or your address is allowed, or you have a shell.
  • To do: The message says when the site is back, in customers' words.
  • To do: Cronjobs that must not run during the window are stopped or paused.
  • To do: A fresh backup exists.

Before switching off:

  • To do: No installation is running (the banner would say so).
  • To do: The site works from an allowed address.

After switching off:

  • To do: The front page answers 200 for everyone, through every server.
  • To do: Caches in front of the site are cleared when content changed.
  • To do: Customers and staff are told the work is done.

Become an Exponential Partner

Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x