Maintenance mode

Maintenance mode shows visitors a short "back soon" page while you work on the site. The page comes with HTTP status 503, which search engines understand as temporary. Logged-in staff keep seeing the normal site, and payment callbacks, the REST API and cron keep working.

Module ID	maintenance
Default	Off
Available	Always
WP-CLI	None. wp shouse module enable maintenance and wp shouse module disable maintenance switch it.
Since	0.1.0

How it works

What visitors get

Maintenance mode stops front-end page views on WordPress's template_redirect hook, at priority 0. A visitor who is not let through gets:

• HTTP status 503.
• A Retry-After header with the Expected duration (minutes) in seconds, never less than 300. The default of 60 minutes gives Retry-After: 3600. The setting starts at 5 minutes, so the lowest value sent is 300.
• An X-Robots-Tag: noindex header and <meta name="robots" content="noindex"> in the page.
• WordPress's no-cache headers. SafeHouse also defines DONOTCACHEPAGE, the constant page cache plugins check before they store a page.

The page is a page of its own, not your theme. It shows the site name, the headline ("We will be back soon" when Headline is empty) and your message, and it follows the visitor's light or dark mode. The browser tab reads HEADLINE – SITE NAME. There is no logo, no stylesheet of your own and no template to override. Because the theme does not run, nothing that plugins add to the theme's <head> or footer appears on it, such as Header and footer scripts.

Who sees the normal site

Logged-in users with the capability chosen in Who sees the normal site see the normal site. Everyone else gets the maintenance page, including logged-in users without that capability.

Option	Capability	With WordPress's standard roles
Administrators	manage_options	Administrators
Anyone who can edit content (default)	edit_posts	Contributors, authors, editors and administrators
Every logged-in user	read	Every logged-in user, subscribers included

WooCommerce customers have only read. With the default option, a logged-in customer gets the maintenance page too. Choose Every logged-in user if customers must reach the shop while it is on.

Maintenance mode never blocks wp-login.php, so staff and customers can log in there. The WooCommerce My Account page is a front-end page, so its login form is behind the maintenance page.

What passes through

These requests are never blocked:

• wp-admin, wp-login.php and admin-ajax.php
• WP-Cron
• the REST API, including the WooCommerce Store API that the block cart and checkout use
• WooCommerce's ?wc-api= callbacks
• WP-CLI
• robots.txt and the favicon

Payment callbacks

A payment callback passes only when the gateway sends it to a ?wc-api= address or to the REST API. SafeHouse has no list of payment gateways and does not detect them. The gateways named under Integrations are for information only. A callback sent to an ordinary front-end page gets the maintenance page like any visitor.

SafeHouse makes no exception based on request headers or the query string, because whoever sends the request controls both. Adding an empty ?wc-api= to a page address does not open the site.

What does not pass

For everyone who cannot see the normal site, every other front-end request gets the maintenance page, including:

• RSS and Atom feeds
• WordPress's XML sitemaps (/wp-sitemap.xml)
• the cart, the checkout page and My Account
• the order confirmation page that a customer returns to after paying

Cache clearing on a switch

Without clearing, a page cache would keep serving the normal pages after you switch maintenance mode on, or the maintenance page after you switch it off. When the module is switched on or off through a settings save (Save Changes, or wp shouse module enable|disable maintenance), SafeHouse:

1. Writes a maintenance warning to the activity log: "Maintenance mode switched on" or "Maintenance mode switched off".
2. Clears these page caches, where they are installed:
   • LiteSpeed Cache, through its litespeed_purge_all action. The same action also clears SafeHouse's own LiteSpeed page cache and Cloudflare cache when those modules run.
   • WP Rocket
   • W3 Total Cache
   • WP Super Cache
   • Autoptimize

Every save of SafeHouse settings also clears the caches of the LiteSpeed page cache and Cloudflare cache modules when they run. Other caches are not cleared: without the Cloudflare cache module, clear Cloudflare page caching (APO or a Cache Everything rule) in the Cloudflare dashboard, and clear a host's server cache with the host's tools.

Changing the headline, message or duration does not run this cache clearing. The maintenance page itself is sent with no-cache headers and DONOTCACHEPAGE, so page caches that honor them do not store it.

The admin bar note

While the module runs, users with manage_options see Maintenance mode is on in the admin bar, on the front end and in wp-admin. It links to the module's settings. Other users who see the normal site, such as editors, do not get the note.

Settings

On SafeHouse → Modules → Maintenance mode, select Details.

Setting	Default	What it does
Headline	Empty	The page heading. Empty shows "We will be back soon". Plain text, up to 200 characters.
Message	Empty	"Basic HTML allowed (links, bold, line breaks)." Up to 2000 characters. Line breaks become paragraphs.
Expected duration (minutes)	60	"Sent to search engines as Retry-After." From 5 to 10080 (7 days).
Who sees the normal site	Anyone who can edit content	Administrators, Anyone who can edit content or Every logged-in user. See Who sees the normal site.

Switch maintenance mode on

1. Go to SafeHouse → Modules → Maintenance mode and select Details.
2. Enter a Headline and a Message.
3. In Expected duration (minutes), enter how long the work should take.
4. In Who sees the normal site, choose who keeps access.
5. Turn on the Maintenance mode switch.
6. Select Save Changes.

The admin bar shows Maintenance mode is on. To check the visitor's view, open the site in a private window.

With WP-CLI:

wp shouse module enable maintenance

This counts as a settings save, so it also clears the caches and writes the log entry.

Switch maintenance mode off

1. Go to SafeHouse → Modules.
2. Turn off the Maintenance mode switch.
3. Select Save Changes.

With WP-CLI:

wp shouse module disable maintenance

Maintenance mode does not end by itself when the expected duration has passed.

Pin it in wp-config.php

To switch maintenance mode from wp-config.php, for example during a deploy, pin it with SHOUSE_MODULES:

define( 'SHOUSE_MODULES', [ 'maintenance' => true ] );

The switch on the settings page is then locked and shows "Pinned by SHOUSE_MODULES in wp-config.php." Set the value to false to switch maintenance mode off. Removing the line hands control back to the switch on the settings page, so maintenance mode stays on if that switch is on.

Changing SHOUSE_MODULES does not go through a settings save. SafeHouse then clears no page cache and writes no activity log entry, so clear your page caches yourself after each change to the line.

What it stores

• The settings in the option shouse_settings.
• A maintenance activity log entry for each switch on or off through a settings save.

It sets no cookies.

Limitations

• No gateway detection. Payment callbacks pass only when they use ?wc-api= or the REST API.
• Feeds and WordPress's sitemaps get the maintenance page.
• Guests returning from a payment see the maintenance page instead of the order confirmation.
• Logged-in WooCommerce customers see the maintenance page unless Who sees the normal site is Every logged-in user.
• There is no way to let a visitor through by IP address or with a secret link. Visitors must log in.
• The page shows a headline and a message only. There is no logo, design option or template.
• Only the caches listed above are cleared, and only on a switch through a settings save. Pinning with SHOUSE_MODULES clears nothing.
• Safe mode stops every module, so the site is public while safe mode is on (see Recover from a lockout).
• It does not switch off by itself.

Related pages

• LiteSpeed page cache
• Cloudflare cache
• Configure in wp-config
• Deploy with git or CI
• Command line reference