How to create custom hostname for Sitecore Edge

When working with Sitecore XM Cloud, we use Edge to retrieve data. Every time the front end makes a request, it calls https://edge.sitecorecloud.io/api/graphql/v1 to fetch the data. Additionally, all images are served from https://edge.sitecorecloud.io/media/.

Naturally, our customer asked if it was possible to change this URL, at least for images. Their SEO team explained that images should have a hostname similar to the site's domain because it improves SEO performance.

At first, I was concerned and thought it would be difficult to implement. I assumed we might need server redirects or some other complex solution. However, after checking Sitecore's documentation, I found a simple way to achieve this. Sitecore provides an option to set a custom hostname for Edge, which allows us to serve images from a domain of our choice.

In this article, I’ll show you how easy it is to configure a custom hostname for Edge using Sitecore’s official guide: Set up a custom hostname.

To set this up, you need to use a service or application that can send requests, as everything is configured through the API: https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames.

To use this API, you also need a bearer token. You can retrieve this token from the Sitecore Cloud portal by following these steps:

1. Open the Sitecore Cloud portal.
2. Click on your account profile image in the top-right corner.
3. Select API Tokens.

After completing these steps, a popup will appear displaying your token. You will need to use this token when making requests to https://edge-platform-admin-api.sitecorecloud.io.

Now, we can create custom hostnames. To do this, you need to send a POST request to: https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames

Make sure to include your bearer token for authentication.

In the request body, use the hostnames parameter, where you specify the custom hostname that will replace the default Edge URL.

As you can see from the screenshot, the initial status will be Pending. This happens because your hostname has not been verified yet.

To complete the verification, you need to configure the hostname and the parameters from the request in your domain settings. Follow these steps:

1. Sign in to your domain registrar using the account you used to purchase your domain.
2. Navigate to the section where you can update your domain's TXT and CNAME records. This is usually called DNS Settings, DNS Management, or Advanced Settings.
3. For hostname validation, add a TXT record using the information from the TXT Hostname Validation section in the Hostname Records dialog.
4. For SSL validation, add a TXT record using the information from the TXT SSL Validation section.
5. Add a CNAME record using the details provided in the CNAME section.

After completing these steps, you will need to wait a little while for the verification process to finish.

To check the status, you can send a GET request to: https://edge-platform-admin-api.sitecorecloud.io/api/admin/v1/hostnames. Make sure to include your bearer token for authentication. If everything is set up correctly, you will receive the following response:

Now, you can use your custom hostname instead of https://edge.sitecorecloud.io/. However, the media URLs will still use https://edge.sitecorecloud.io/.

To replace the media hostname, I followed these steps and encountered some challenges along the way.

First, I tried using the Sitecore_Media_MediaLinkServerUrl parameter, which can be set as an environment variable in the Sitecore Cloud portal. Unfortunately, this parameter only works for Content Management (CM) and does not affect media URLs in Edge.

Next, I contacted Sitecore Support and asked if there was a way to change the media hostname. Sitecore responded quickly, stating:

"There is no out-of-the-box functionality to control the media URL hostname when publishing to Edge. By default, these media links will use the edge.sitecorecloud.io domain."

However, they also suggested using Next.js rewrites (Next.js documentation).

This approach worked for me, though it took some time to implement. In the end, I successfully replaced the media URLs with my custom hostname. Of course, this is just a workaround, but I hope Sitecore will eventually support Sitecore_Media_MediaLinkServerUrl for Content Delivery (CD) as well.

Conclusion

I'm really happy that Sitecore has considered some of the customization needs customers might have and provided easy configuration options, such as setting up a custom hostname for Edge.

Thank you for reading!