writing a maintenance page

maintenance-page-how-to.md

How to set up a maintenance page on Cloudflare Workers

overview

the TL;DR here is that we are uploading your site assets to cloudflare workers kv, to be served from cloudflare's edge network by a custom Worker, defined in the workers-site directory. the publish command below does all the work of uploading the assets and deploying the necessary worker. maintenance pages are a nice use case, since the worker intercepts all traffic through its configured route while it is up.

build your assets

This can be just a basic HTML page with images, or it can be from a static site generator. what's important is the built assets.

install wrangler and log in (requires a Cloudflare account)

TL;DR of the cloudflare workers quick start guide

$ npm i -g @cloudflare/wrangler
$ wrangler login # will ask you to open a browser and create an api token for use by wrangler.

Note: by default the api token created during wrangler login includes access to all accounts and zones associated with your login. you can edit these permissions at https://dash.cloudflare.com/profile/api-tokens

create a workers site project

$ wrangler generate --site
$ cd worker

add your assets

add all built static assets to the public folder in the newly created worker directory

configure your wrangler project

you'll need the account id associated with the site you want to use. run wrangler whoami or find it in the cloudflare dashboard. Add it to the wrangler.toml:

name = "site-worker"
type = "webpack"
account_id = "" # add your account id here
workers_dev = true
route = ""
zone_id = ""

[site]
bucket = "./public" # this points to your built assets

upload the worker

run wrangler publish and preview your worker at the output url (in this example https://site-worker.alew.workers.dev):

$ wrangler publish
✨  Built successfully, built project size is 13 KiB.
🌀  Using namespace for Workers Site "__worker-workers_sites_assets"
✨  Success
🌀  Uploading site files
✨  Successfully published your script to
 https://site-worker.alew.workers.dev
💁  Deleting stale files...

cut over to the worker

when it is time to set up the maintenance page, go to the cloudflare workers routes dashboard (https://dash.cloudflare.com/workers/routes) and point the appropriate routes at your new worker.

ROUTES

IMPORTANT if you have existing workers whose route configurations are more specific, you will need to delete those routes! take note of them so you can restore when maintenance is complete.

Workers routes are (approximately) applied in order of specificity, i.e. if you have a worker "A" running at www.foo.com/* and another "B" running at www.foo.com/bar/*, then when you hit www.foo.com/bar/baz, worker "B" will execute. See the cloudflare docs for more information.

Workers do not stack; one will run or none will run. As such, the order of operations should go as follows:

1. add the route for your maintenance site worker
2. remove (and note!) any routes that might override the maintenance worker's route
3. do maintenance
4. reinstate any routes removed during step 2
5. remove the maintenance wite worker route

cut back

when it is time to remove the maintenance page, re-set your workers routes to their pre-maintenance configurations. remove the route to the maintenance worker.