How to enable custom maintenance page in Fastly

August 25, 2025·

·Reading time: 5 minutes

This step-by-step guide outlines how to create and maintain a custom maintenance page in Fastly, and how to enable and disable it either manually or during Upsun deployments.

We need to add a dictionary in Fastly which we will use as an on / off switch to enable and disable the maintenance page as well as the content of maintenance page.

We are going to use official Fastly CLI tool which you can download from Fastly CLI. You will need a Fastly API token with permissions to perform changes.

We are going to use these two environment variables:

FASTLY_SERVICE_ID: Contains our Fastly service ID.
FASTLY_API_TOKEN: Contains our Fastly API token.

Create Fastly configuration

Please define these two local environment variables before starting, using the following command lines:

Terminal

export FASTLY_SERVICE_ID=<YOUR-FASTLY-SERVICE-ID>
export FASTLY_API_TOKEN=<YOUR-FASTLY-API-TOKEN>

Let’s start with cloning the active configuration version:

Terminal

fastly service-version clone -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version active

SUCCESS: Cloned service $FASTLY_SERVICE_ID version X to version Y

From now on, we will work on our cloned version by referring to it with --version latest.

Let’s create a dictionary which will be used as on & off switch to enable and disable the maintenance page:

Terminal

fastly dictionary create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance

SUCCESS: Created dictionary maintenance (id zHpEamIhKjDt7B28bSyRw4, service $FASTLY_SERVICE_ID, version Y)

Make a note of the given dictionary ID and let’s store it on a variable:

Terminal

export FASTLY_MAINTENANCE_DICT=zHpEamIhKjDt7B28bSyRw4

Let’s add an entry in the new dictionary which will be the actual on/off switch:

Terminal

fastly dictionary-entry create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=false

SUCCESS: Created dictionary item maintenance (service $FASTLY_SERVICE_ID, dictionary $FASTLY_MAINTENANCE_DICT)

We need a VCL to check for the key in the dictionary to know whether to return the maintenance page or not. Save the following VCL snippet in maintenance_recv.vcl:

maintenance_recv.vcl

if (table.lookup(maintenance, "maintenance", "false") == "true") {
   error 653 "maintenance";
}

Let’s upload this maintenance_recv.vcl VCL to Fastly:

Terminal

fastly vcl snippet create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_recv --type recv --priority 50 --content maintenance_recv.vcl

SUCCESS: Created VCL snippet 'maintenance_recv' (service: $FASTLY_SERVICE_ID, version: Y, dynamic: false, snippet id: KdpZbSaxdj4bqP3kwKHt41, type: recv, priority: 50)

Save the maintenance page inside a VCL called maintenance_error.vcl like below. Note maintenance page goes within HTML tags:

maintenance_error.vcl

if (obj.status == 653) {
  set obj.status = 200;
  set obj.response = "OK";
  synthetic {"
    <html>
      <head>
      </head>
      <body>
        <h1>This site is under maintenance</h1>
      </body>
    </html>
  "};
  return(deliver);
}

Let’s create the maintenance_error.vcl VCL with the maintenance page in Fastly:

Terminal

fastly vcl snippet create -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_error --type error --content maintenance_error.vcl

SUCCESS: Created VCL snippet 'maintenance_error' (service: $FASTLY_SERVICE_ID, version: Y, dynamic: false, snippet id: 3BcskRs1Z2Fo9GqidDwDf0, type: error, priority: 100)

We can now activate our changes:

Terminal

fastly service-version activate -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest

SUCCESS: Activated service $FASTLY_SERVICE_ID version Y

Testing

From now on, we can enable and disable our maintenance page in Fastly on demand by altering the key in the dictionary. We can enable it by setting the key value to true:

Terminal

fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=true

SUCCESS: Updated dictionary item (service $FASTLY_SERVICE_ID)

Dictionary ID: $FASTLY_MAINTENANCE_DICT
Item Key: maintenance
Item Value: true

Bear in mind it will take several seconds for Fastly to propagate the key value among their edge servers. You can browse to our website and check how the maintenance page is being served by Fastly.

We can disable the maintenance page by altering the key to false in the dictionary:

Terminal

fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=false

SUCCESS: Updated dictionary item (service $FASTLY_SERVICE_ID)

Dictionary ID: $FASTLY_MAINTENANCE_DICT
Item Key: maintenance
Item Value: false
Maintenance page will disappear and the website will be live again.

Enable maintenance during deployment

If we want to display the maintenance page during deployment, we can do so by adding the variables and enable followed disable the page in the deployment hooks.

We can add the variables to our project like below:

Terminal

upsun variable:create -p <PROJECT_ID> -e <PROD_ENVIRONMENT> --level environment --inheritable false --visible-build true --prefix env --no-wait --name FASTLY_SERVICE_ID --value $FASTLY_SERVICE_ID
upsun variable:create -p <PROJECT_ID> -e <PROD_ENVIRONMENT> --level environment --inheritable false --visible-build true --prefix env --no-wait --sensitive true --name FASTLY_API_TOKEN --value $ FASTLY_API_TOKEN
upsun variable:create -p <PROJECT_ID> -e <PROD_ENVIRONMENT> --level environment --inheritable false --visible-build true --prefix env --no-wait --name FASTLY_MAINTENANCE_DICT --value $FASTLY_MAINTENANCE_DICT

Note: Replace <PROJECT_ID> and <PROD_ENVIRONMENT> with your Upsun project info.

Example:

<PROJECT_ID> = azertyuiop1234
<PROD_ENVIRONMENT> = main

We add enable and disable maintenance commands at the end of build and deploy hooks respectively:

.upsun/config.yaml

applications:
  app:
    hooks:
      build: |
        set -e
        #...
        brew install fastly/tap/fastly
        fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=true        
    
      deploy: |
        set -e
        #...
        fastly dictionary-entry update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --dictionary-id $FASTLY_MAINTENANCE_DICT --key maintenance --value=false

💡

Please note:

The above commands can also be applied to Platform.sh projects by replacing upsun CLI by platform CLI in the call.

Updating maintenance page

What if we want to update the maintenance page in the future?

For doing so, we update maintenance_error.vcl with our updated maintenance page within HTML tags. We create a new version, upload it and activate in Fastly:

Terminal

fastly service-version clone -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version active
fastly vcl snippet update -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest --name maintenance_error --type error --content maintenance_error.vcl
fastly service-version activate -t $FASTLY_API_TOKEN -s $FASTLY_SERVICE_ID --version latest

Summary

With your Fastly maintenance page configured, you can now automatically enable maintenance page in Fastly during deployments to Upsun. This setup provides:

Create Fastly configuration to enable custom maintenance page
Automatically enable maintenance page during deployments
Maintain custom maintenance page

For more advanced configurations, explore Upsun’s API documentation to customize environment settings, manage resources, and integrate with your existing DevOps tools.

Create your Upsun account today.

Last updated on August 25, 2025