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​

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