How to deploy to Akamai NetStorage

Introduction

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

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. Akamai account with NetStorage enabled.
4. Uniform Upload Tool for Akamai NetStorage (optional).

Media Sync

A future version of Uniform will support media sync to Akamai NetStorage. Currently you must either host media files on your Sitecore CD instance or use media sync to a supported system (e.g. Azure Blob Storage).

Steps

Add storage group

1. Log into Akamai.

2. In the left menu, navigate to ORIGIN SERVICES > NetStorage.

3. In the left menu, click Storage Groups.

4. Click + Add Storage Group.

5. Enter values for the fields and click Next.

6. Select the zones you want to use and click Next.

7. Click Next.

8. Click + Upload Directory.

9. Enter a value in the Name field and click Create.

10. Enter the following values and click Save:

    • Quick Delete - enabled
    • Index Name - /index.html

    

11. Click Next.

12. Click Next.

13. Click Create.

14. You should see your storage group in the list.

    note

    It takes from 1-2 hours for the storage group to be propagated to the NetStorage network. You can continue to configure Akamai during this time.

Add upload account

1. In Akamai, in the left menu navigate to ORIGIN SERVICES > NetStorage.
2. In the left menu, click Upload Accounts.
3. Click + Add Upload Account.
4. Complete the form, then click Next.
5. Tick the box next to the storage group you created in the previous section, then click Next.
6. Click Netstorage HTTP CMS API.
7. Click + Add HTTP API Key.
8. Click Save.
9. Click File Manager.
10. Enable the option "Enable File Manager Access", then click Next.
11. Click Next.
12. Click Create.
13. You should see your upload account in the list.

    note

    It takes from 1-2 hours for the upload account to be propagated to the NetStorage network. You can continue to configure Akamai during this time.

Add property

1. In Akamai, in the left menu navigate to CDN > Properties.

2. Click New Property.

3. In the product "Ion Standard", click Create Property.

4. Click Property Manager.

5. Complete the form, then click Next.

6. In the section Property Hostnames, click Add.

7. Add the hostname for the site, then click Next.

8. Click Next.

9. Click Submit.

10. Click Close.

11. Scroll down to the section Property Configuration Settings.

12. Click Default Rule.

13. In the section Behaviors, find the behavior Origin Server.

14. Enter the following values:

    • Origin Type - NetStorage
    • NetStorage Account - Select the storage account you created in the earlier section.

    

15. Under Default Rule, navigate to Offload origin.

16. In the section Behaviors, find the behavior Caching.

17. Set the following values:

    • Caching option - Cache
    • Maxage - 10 minutes

    

18. Under Default Rule, navigate to Offload origin > HTML pages.

19. In the section Behaviors, find the behavior Caching.

20. Set the following values:

    • Caching option - Cache
    • Maxage - 10 minutes

    

21. Click Add Behavior.

22. Select ESI (Edge Side Includes) and click Insert Behavior.

23. Click Add Behavior.

24. Select Downstream Cacheability and click Insert Behavior.

25. Scroll down to the behavior.

26. For the value Caching Option, select Don't allow caching (bust).

27. (optional) If you are personalizing based on geographic location, click Insert Behavior.

28. (optional, continued) Select Content Targeting (EdgeScape) and click Insert Behavior.

29. (optional) If you are personalizing based on device characterization, click Insert Behavior.

30. (optional, continued) Select Device Characterization - Forward in Header and click Insert Behavior.

31. (optional, continued) Scroll down to the behavior.

32. (optional, continued) Select the following characterizations:

    • brand_name
    • device_os
    • device_os_version
    • is_mobile
    • is_tablet
    • marketing_name
    • mobile_browser
    • mobile_browser_version
    • model_name

    

33. Under Default Rule, navigate to Augment insights > Traffic reporting.

34. In the section Behaviors, find the behavior Content Provider Code.

35. Click Create new....

36. Enter a name for the CP code and click Create.

37. Scroll to the top of the page and click Save.

38. Click the tab Activate.

39. Click Activate v1 on Production.

40. Tick the checkbox at the top of the page.

41. Scroll to the bottom of the page and click Activating v1 on Production.

Install Uniform Upload Tool (optional)

The Uniform deployment process uploads files to Akamai NetStorage. By default, Uniform uses the Akamai NetStorage API to do this. Uniform also provides an upload tool that offers improved performance. This is a tool that is triggered by the Uniform service during the deployment process.

important

Make sure you have a version of the Uniform Upload Tool that is compatible with the operating system on which the Uniform service is running. Windows and Linux are supported.

1. Copy the upload tool to a folder on the machine that runs the Uniform service.
2. Make sure the Uniform service has access rights to the upload tool.

Collect settings

In order for the Uniform deployment process to be able to upload static files to Akamai NetStorage, several settings must be configured.

The section describes how to find these settings.

1. In Akamai, in the left menu, navigate to ORIGIN SERVICES > NetStorage.
2. In the left menu, click Storage Groups.
3. Click the row for the storage group you created in the previous section.
4. Note the value of HTTP Domain Name.
5. In the left menu, click Upload Accounts.
6. In the section Upload Account Details, note the value Id.
7. In the section Upload Directories, note the value Upload Directory. This is the CP code for the upload directory.
8. Click the button Edit.
9. In the section Access Methods, click Netstorage HTTP CMS API.
10. In the column Actions, click the icon Copy Key. Note the value copied into the clipboard.
11. At the bottom of the page, click the button Cancel.
12. If you are using the optional Uniform Upload Tool, note the path to the executable (e.g. If your Uniform service is running on Windows, the path might be D:\tools\uniform\Uniform.Akamai.Upload.exe).

Configure deployment service

The deployment service in Sitecore is responsible for triggering the Uniform service during the Sitecore publishing process. In order to trigger the Uniform service, a number of settings must be added to Sitecore. These settings are used in several ways:

• Locate the Uniform service.
• Provide settings to the Uniform service that are used to communicate with Akamai.

There are two ways you can configure these settings.

Option 1. Sitecore config files

This option is recommended for production environments.

<sitecore>    <uniform>      <siteConfigurations>        <siteConfiguration name="<YOUR-SITECORE-SITE-NAME>">          <site inherits="<YOUR-SITECORE-SITE-NAME>"/>          <deployment>            <deploymentService set:ref="uniform/services/hostedDeploymentService">              <ServiceUrl><URL-TO-UNIFORM-SERVICE></ServiceUrl>              <environmentVariables hint="raw:AddEnvironmentVariable">                              <variable name="UNIFORM_PUBLISH_TARGET">akamai</variable>                <variable name="AKAMAI_NETSTORAGE_HOSTNAME"><YOUR-HTTP-DOMAIN-NAME></variable>                <variable name="AKAMAI_NETSTORAGE_KEY"><YOUR-HTTP-API-KEY></variable>                <variable name="AKAMAI_NETSTORAGE_ID"><YOUR-ACCOUNT-ID></variable>                <variable name="AKAMAI_NETSTORAGE_CPCODE"><YOUR-UPLOAD-DIRECTORY-CP-CODE></variable>                <variable name="AKAMAI_NETSTORAGE_UPLOAD_TOOL_PATH"><YOUR-UPLOAD-TOOL-PATH></variable>              </environmentVariables>            </deploymentService>                 </deployment>        </siteConfiguration>      </siteConfigurations>    </uniform>  </sitecore>

note

If you are not using the Uniform Upload Tool, you should remove the variable AKAMAI_NETSTORAGE_UPLOAD_TOOL_PATH.

Option 2. Sitecore items

1. In Sitecore, open Content Editor.
2. Navigate to sitecore > system > Uniform > Site Configurations.
3. Select the item that corresponds to your site.
4. Add a new item using the template Configure Site.
5. Enter the following field values:
   • Inherits: <YOUR-SITECORE-SITE-NAME>
6. Save the item.
7. Add a new item using the template Connect: Self-Hosted Deployment Service....
8. Enter the following field values:
   • ServiceUrl: Url to the Uniform service that is used to generate static pages. (For example, if you are using Next.js, this is the url to the Next.js application.)
9. In the field EnvironmentVariables, enter the following values:
   • UNIFORM_PUBLISH_TARGET = akamai
   • AKAMAI_NETSTORAGE_HOSTNAME = <YOUR-HTTP-DOMAIN-NAME>
   • AKAMAI_NETSTORAGE_KEY = <YOUR-HTTP-API-KEY>
   • AKAMAI_NETSTORAGE_ID = <YOUR-ACCOUNT-ID>
   • AKAMAI_NETSTORAGE_CPCODE = <YOUR-UPLOAD-DIRECTORY-CP-CODE>
10. If you are using the Uniform Upload Tool, add the following values to the field EnvironmentVariables:
    • AKAMAI_NETSTORAGE_UPLOAD_TOOL_PATH = <YOUR-UPLOAD-TOOL-PATH>
11. Save the item.

Configure cache purge

When a file in NetStorage is changed, the Akamai cache must be purged in order for Akamai to deliver the latest version of the file.

Follow the instructions on how to configure cache purge.

important

For the CP code, you should use the value for your upload directory, meaning the value set for the environment variable AKAMAI_NETSTORAGE_CPCODE.

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

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 Akamai, navigate to your property.
2. In the section Active Production Version, click the link next to Version:.
3. In the section Property Hostnames, find the value of Edge Hostname.
4. In your DNS settings, add a CNAME record using the Edge Hostname value.

Troubleshooting

File Manager setup

Akamai offers a tool named File Manager that gives you the ability to view the files in NetStorage from the Akamai Control Center.

1. Log into Akamai.
2. In the left menu, navigate to ORIGIN SERVICES > NetStorage.
3. Click File Manager.
4. Click Setup FM Access.
5. In the row for your storage group, select the upload account you created, then click Update Access.
6. Click File Manager.
7. Click the name of your storage group.
8. Now you can access the files in the storage group.