How to deploy to Cloudflare Workers (production)

important

In a future release Uniform will provide instructions on how to configure a production environment using KV storage in a way that ensures uptime. In the meantime, it is recommended that a different storage location (e.g. Azure Blob storage) be used for production environments.

If you are configuring a development or test environment, you might want to use the instructions in How to deploy to Cloudflare Workers (development). That guide uses Cloudflare for request handling and storage (as opposed to these instructions that use Cloudflare for request handling and Azure Blob Storage for file storage).

Introduction

The following diagram illustrates the components involved with deploying a Sitecore site to Cloudflare.

Prerequisites

1. You have completed the Getting Started section, so your site is ready to be deployed to static storage.
2. Uniform for Sitecore starter kit (for Deploy).
3. Cloudflare account with the ability to create new sites.

   Cloudflare's free tier is sufficient for development and test environments.

Steps

Configure site to deploy to Azure Blob Storage

Follow the instructions in How to deploy to Azure Blob Storage.

Add Cloudflare site

1. Log into Cloudflare.
2. Select your account.
3. Click Add Site.
4. Enter the domain name for your site and click Add site.
5. Select a pricing plan and click Continue.
6. Cloudflare will display the DNS records for your domain. Click Continue.

   In order to use Cloudflare as a CDN, you will need to configure DNS so routes to your site can be resolved. This is covered in a later step.

Create API token

1. In Cloudflare, select your site.
2. On the righthand side of the screen, scroll to the section API.
3. Click Get your API token.
4. Click Create Token.
5. In the row "Edit Cloudflare Workers", click Use template.
6. In the section "Permissions", set the following:
   • Account > Workers Scripts > Edit
   • Zone > Workers Routes > Edit
   • Account > Account Settings > Read
   • User > User Details > Read
   • Account > Workers Tail > Read
7. In the section "Account Resources", set the following:
   • Include > <YOUR-ACCOUNT-ID>
8. In the section "Zone Resources", set the following:
   • Include > Specific zone > <YOUR-ZONE-ID>
9. Click Continue to summary.
10. Click Create Token.
11. The token value is displayed. Note this value.

    This is the only time the token value is displayed. If you lose it you will need to create a new token.

Collect settings

During the deployment process, Uniform installs and configures the required components on Cloudflare, but performing these tasks requires several settings from Cloudflare to be configured in Sitecore.

The section describes how to find these settings.

1. The first value to determine is the route (i.e. url) you want the worker to handle. Wildcard character (i.e. *) are supported.

   For example, if your site is cdn.example.com and you want the worker to handle all urls on the site, you would enter cdn.example.com/*.

2. In Cloudflare, select your site.
3. On the righthand side of the screen, scroll to the section API.
4. Note the value of Account ID.
5. In the top navigation, click Workers.
6. Click Manage Workers.
7. Note the value of Your subdomain.

Create the worker

The worker is the component response for handing the page request. It basically is just a function that runs on Cloudflare's CDN. Cloudflare handles all of the work required to make the worker available globally.

When you are only using Deploy (i.e. you are not using Optimize for Sitecore to handle personalization) the Cloudflare worker you need to deploy is very simple: it retrieves content from storage.

The following diagram illustrates the request handling process with the worker (using Azure Blob Storage):

For a production environment, you are responsible for deploying the worker. While Uniform does not put any restrictions on the worker itself (i.e. you can implement any logic you want), there are some conventions that must be followed (especially in the wrangler.toml file) in order for the Uniform service to be able to deploy the worker properly.

The Uniform starter kit provides the files you need. You should consider these files a starting point. You can add whatever logic you need to the worker.

1. Copy the worker files from the Uniform starter kit to a folder cloudflare-worker under the root folder of your Uniform service.
   • package.json
   • package-lock.json
   • index.js
   • wrangler.toml
   • wrangler-webpack.config.js
2. In the file wrangler.toml, set the following values:
   • account_id = <YOUR-ACCOUNT-ID>
   • zone_id = <YOUR-ZONE-ID>
   • api_token = <YOUR-API-TOKEN>
   • name = <YOUR-WORKER-NAME>
   • route = <YOUR-WORKER-ROUTE>
3. Enter the following command:

   wrangler publish

Start Uniform service

1. In the terminal window, navigate to the root folder of your Uniform service.
2. Enter the following command:

   npm run start

Trigger deployment

1. In Sitecore, republish of any page-level item under the /sitecore/content/<YOUR-SITECORE-SITE-NAME> item.
2. The console for your Uniform service will show something like the following:

   07/05-10:44:34  info: Received deploy status request, ticket: 0, message: Uploading HTML site files07/05-10:44:35  info: Successfully deployed C:\sitecore-jss-nextjs-starterkit\.temp\0 folder07/05-10:44:35  info: Deleting temp dir: C:\sitecore-jss-nextjs-starterkit\.temp\007/05-10:44:36  info: Temp dir was deleted: C:\sitecore-jss-nextjs-starterkit\.temp\007/05-10:44:36  info: Received deploy status request, ticket: 0, message: Deployment is complete

3. Open your site on Cloudflare using the url https://<YOUR-WORKER-NAME>.<YOUR-ACCOUNT-NAME>.workers.dev.
4. The site should render normally.

   It is possible the site will not render correctly because you are not accessing the site through the expected domain. The section below on configuring DNS will guide you through the steps needed to fix this.

Configure DNS

You should talk with your network administrator before making any changes to DNS. The instructions below may not be appropriate for your environment.

1. In Cloudflare, navigate to your site.
2. In the top menu, click DNS.
3. In your domain registrar, set the nameservers assigned to your domain to the nameservers listed in Cloudflare.
4. Click Add record.
5. Enter the following values:
   • Type: A
   • Name: <YOUR-SUBDOMAIN> (e.g. cdn)
   • IPv4 address: 192.0.2.1

     The IP address entered here is not used, but DNS requires a value be entered. Cloudflare will use the worker with a route that matches this record.

6. Click Save.
7. Open your site on Cloudflare using the url https://<YOUR-SUBDOMAIN>.<YOUR-DOMAIN>.

Configure caching

Cloudflare does not automatically enable caching on worker routes. You must enable this.

1. In Cloudflare, navigate to your site.
2. In the top menu, click Rules.
3. Click Create Page Rule.
4. In the first text box enter your route (e.g. cdn.example.com/*).
5. In the dropdown select SSL > Full.
6. In the dropdown select Cache Level > Cache Everything.
7. In the dropdown select Edge Cache TTL > 2 hours.
8. Click Save and Deploy.

note

Normally you would want to configure a purge service on the Uniform deployment service in order to ensure that the cache is purged when new content is published. The way Uniform deploys files to Cloudflare, Cloudflare automatically purges the cache. No purge service is required.