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.
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).
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'
- 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.
import { defineConfig } from "@front-commerce/core";
export default defineConfig({
maintenance: {
authorizedIps: ["127.0.0.1", "83.65.12.111", "2ce8:c427::7156:ad8e"],
},
});
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.
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.
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