Skip to main content
Version: 3.x

Since version 3.6

Maintenance Mode

You may want to put one or more of your stores in maintenance mode while you do some maintenance work/deployment tasks on your store(s).

Front-Commerce comes with an API that allows you to put/remove a store in maintenance mode. To enable the maintenance mode API you need to set the FRONT_COMMERCE_MAINTENANCE_MODE_AUTHORIZATION_TOKEN environment variable.

.env
FRONT_COMMERCE_MAINTENANCE_MODE_AUTHORIZATION_TOKEN=a-secret-token

Once you have setup the FRONT_COMMERCE_MAINTENANCE_MODE_AUTHORIZATION_TOKEN environment variable the maintenance mode API will be available after restarting the server

The Maintenance Mode API​

Global Maintenance Mode (All Stores)​

If you want to put all stores into maintenance mode at once, use the global maintenance mode API endpoint, typically available at your main application domain (not a specific store subdomain).

info

If you have a multi-store setup, you can activate the maintenance mode for a specific store by using the /api/store-maintenance-mode endpoint on any of your stores, to enable maintenance mode on all stores, you can run the global maintenance mode endpoint on any of your stores, for example

  • Store A: https://store-a.example.com/api/maintenance-mode
  • Store B: https://example.com/store-b/api/maintenance-mode

If your main application is accessible at https://www.example.com/, you can activate global maintenance mode with:

curl --location --request POST 'https://www.example.com/api/maintenance-mode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "a-secret-token"
}'

To set a duration (in milliseconds) for the global maintenance mode:

curl --location --request POST 'https://www.example.com/api/maintenance-mode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "a-secret-token",
    "duration": 3600000
}'

To deactivate global maintenance mode for all stores:

curl --location --request DELETE 'https://www.example.com/api/maintenance-mode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "a-secret-token"
}'

To check the global maintenance mode status:

curl --location --request GET 'https://www.example.com/api/maintenance-mode'
note
  • The /api/maintenance-mode applies maintenance mode to all stores (global maintenance mode).
  • The /api/store-maintenance-mode endpoint on a specific store's domain applies maintenance mode only to that store.

Activating Maintenance Mode for a Specific Store​

Since version 3.13

If your Front-Commerce application serves multiple stores (multi-store setup), you can activate maintenance mode for a specific store by sending the request to the API endpoint on that store's base URL.

For example, if you have two stores:

  • Store A: https://store-a.example.com/
  • Store B: https://store-b.example.com/

To activate maintenance mode for Store A:

curl --location --request POST 'https://store-a.example.com/api/store-maintenance-mode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "a-secret-token"
}'

To activate maintenance mode for Store B:

curl --location --request POST 'https://store-b.example.com/api/store-maintenance-mode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "a-secret-token"
}'

You can also set a duration (in milliseconds) for the maintenance mode:

curl --location --request POST 'https://store-a.example.com/api/store-maintenance-mode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "a-secret-token",
    "duration": 3600000
}'

Deactivating Maintenance Mode for a Specific Store​

Since version 3.13

To deactivate maintenance mode for a specific store, send a DELETE request to the same endpoint on the store's base URL:

curl --location --request DELETE 'https://store-a.example.com/api/store-maintenance-mode' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "a-secret-token"
}'

Checking Maintenance Mode Status for a Specific Store​

Since version 3.13

To check if a specific store is in maintenance mode, send a GET request to the endpoint on that store's base URL:

curl --location --request GET 'https://store-a.example.com/api/store-maintenance-mode'

Bypassing Maintenance Mode​

Bypassing with Authorized IPs​

To bypass the maintenance mode for certain IP addresses, you can configure the maintenance.authorizedIps in your front-commerce.config.ts file.

front-commerce.config.ts
import { defineConfig } from "@front-commerce/core";

export default defineConfig({
  maintenance: {
    authorizedIps: ["127.0.0.1", "83.65.12.111", "2ce8:c427::7156:ad8e"],
  },
});
Please configure both v4 and v6 IP addresses as much as possible.

To retrieve your IP address, you can use What Is My IP or via the curl command:

$ curl ifconfig.me -6
# 2ce8:c427::7156:ad8e
$ curl ifconfig.me -4
# 83.65.12.111

Bypassing with Authorized Header​

If you want to bypass the maintenance mode using a specific HTTP header, you can configure the maintenance.authorizedHeader in your front-commerce.config.ts file. This allows the maintenance mode to be bypassed if the request contains the specified header with a non-empty value.

front-commerce.config.ts
import { defineConfig } from "@front-commerce/core";

export default defineConfig({
  maintenance: {
    authorizedHeader: "X-Maintenance-Mode-Bypass",
  },
});

In your request, include the header as follows:

curl --location --request GET 'https://example.com/acme-page' \
--header 'X-Maintenance-Mode-Bypass: true'

This will allow the request to bypass the maintenance mode if the header is present.

caution

You are responsible for ensuring that the header is persisted in the request. When navigating to a new page, the header might not be included automatically. Consider implementing a solution to consistently add the header to all requests if you need persistent maintenance mode bypass, such as:

  • Using an HTTP client that allows setting default headers
  • Configuring your reverse proxy to add the header
  • Setting up browser extensions that can inject headers