Skip to content

Maintenance Mode

SWS provides a way to put a server into a maintenance mode. Allowing the server to respond with a custom HTTP status code and HTML content always by default.

This is useful to allow the server to be taken offline without disrupting the service.

The feature is disabled by default and can be controlled by the boolean --maintenance-mode option or the equivalent SERVER_MAINTENANCE_MODE env.

How it works

When the feature is enabled, SWS will respond always with the specified (or default) status code and HTML content to every request ignoring all SWS features. Except the Health check, CORS and Basic Authentication features.

HTTP Status Code

The --maintenance-mode-status or the equivalent SERVER_MAINTENANCE_MODE_STATUS env variable can be used to tell SWS to reply with a specific status code.

When not specified, the server will reply with the 503 Service Unavailable status.

HTML Page

The --maintenance-mode-file or the equivalent SERVER_MAINTENANCE_MODE_FILE env variable can be also used to customize the response content.

The value should be an existing local HTML file path. When not provided a generic message will be displayed.

Optional

Remember that either --maintenance-mode-status and --maintenance-mode-file are optional and can be omitted as needed.

Independent path

The --maintenance-mode-file is an independent file path and not relative to the root.

Example

For instance, the server will respond with a 503 Service Unavailable status code and a custom message.

static-web-server -p 8787 -d ./public \
    --maintenance-mode \
    # optional status code, `503` by default
    --maintenance-mode-status=503 \
    # optional HTML page, generic message by default
    --maintenance-mode-file="./maintenance.html"