How to use CDN on your website

To start using CDN on your website you need to configure:

1. the reverse proxy caching server such as Azure CDN (externally)
2. the CDN Publisher on your website
3. [optionally] redirects for protected files via the CDN Publisher configuration if your website features extranet.

We assume that you have already configured your CDN endpoint on Azure CDN or other reverse proxy caching server and have the endpoint's hostname handy.

CDN Publisher configuration

The CDN Publisher configuration is located in: ~/App_Config/Orckestra.Media.CdnPublisher.config.

Here you can:

• specify the URL to the CDN endpoint
• specify the hosts the CDN must be used
• rules for caching
• redirects for C1 pages and protected C1 media

The CDN Publisher comes with a predefined cache profile that includes a few rules for caching. When configuring CDN Publisher, in the basic scenario, you will need to at least specify the CDN endpoint's URL and hosts to use CDN on.

There are two major setups that reflect in the CDN Publisher configuration:

• Simple Setup: a single website that serves for both content management (CM) and content delivery (CD)
• CM / CD Setup: a multi-site environment that features a website for content management (CM node) and one or more public website for content delivery (CD node(s))

Each setup option requires separate hostnames for specific purposes.

Simple Setup

• A website that runs C1 CMS 6.3 or later
• 2 hostnames pointing to the website:
  • Public (for example, 'www.contoso.com')
  • CDN source (for example, 'cdnsource.contoso.com')

CM / CD Setup

• Websites:
  • A CM node (“staging” website) that runs C1 CMS 6.3 or later.
  • One or more CD nodes (“production” or “live” websites) that run C1 CMS 6.3 or later.
• 2 or more hostnames pointing to the websites as follows:
  • One or more public hostname(s) for public websites as the CD nodes (for example, 'www.contoso.com', 'contoso.com')
  • A hostname for the CDN source as a CD node, too (for example, 'cdnsource.contoso.com')
  • The hostname for the CM node is not relevant for the setup

Configuring CDN Publisher (simple setup)

For the simple setup:

1. Edit ~/App_Config/Orckestra.Media.CdnPublisher.config.
2. Set the CDN information in the <cdn/> element:
   • cdnEdgeUrl: specify the CDN endpoint hostname (for example, 'contoso.azureedge.net')
   • enabledOnHosts: use “*” (for all hostnames)
3. Keep other defaults the config comes with (the cache profile name and rules), or configure the rules as needed.
4. Wait until the endpoint will propagate through the CDN (90 minutes or so).

Example:

Expand code

<?xml version="1.0" encoding="utf-8"?> 
<Orckestra.Media.CdnPublisher> 
  <cdn> 
    <add cdnEdgeUrl="//contoso.azureedge.net" enabledOnHosts="*" cacheProfile="shared" /> 
  </cdn> 
  <redirects> 
  </redirects> 
  <cacheProfiles> 
    <add name="shared"> 
      <rules> 
		<add paths=".js,.css,.less,.sass,.jpg,.png" cache="true" timestampCdnUrl="true" />
		<add paths="/frontend/*" cache="true" timestampCdnUrl="true" />
		<add paths="/media/*" cache="true" timestampCdnUrl="false" />
		<add paths="/bundles/*" cache="true" timestampCdnUrl="false" />
      </rules> 
    </add> 
  </cacheProfiles> 
</Orckestra.Media.CdnPublisher>

1. In your browser, open a page with the URLs to media or static website files handled by the caching rules.
2. Check these URLs (hover over them where possible, or open them in other browser tabs).

The hostname in the URLs should be that of the CDN endpoint you have configured above. Once the endpoint propagate through the CDN, the files will be available on your website.

Configuring CDN Publisher (CM / CD setup)

For the CM / CD setup:

1. Edit ~/App_Config/Orckestra.Media.CdnPublisher.config
2. Set the CDN information in the <cdn/> element:
   • cdnEdgeUrl: specify the CDN endpoint hostname (for example, 'contoso.azureedge.net')
   • enabledOnHosts: specify the public hostname(s) (for example, 'www.contoso.com, contoso.com'). Use wildcards if necessary.
3. Keep other defaults the config comes with (the cache profile name and rules), or configure the rules as needed.
4. Publish the changes form the CM node to all the CD nodes.
5. Wait until the endpoint will propagate through the CDN (90 minutes or so).

Example:

Expand code

<?xml version="1.0" encoding="utf-8"?> 
<Orckestra.Media.CdnPublisher> 
  <cdn> 
    <add cdnEdgeUrl="//contoso.azureedge.net" enabledOnHosts="www.contoso.com,contoso.com" cacheProfile="shared" /> 
  </cdn> 
  <redirects> 
  </redirects> 
  <cacheProfiles> 
    <add name="shared"> 
      <rules> 
		<add paths=".js,.css,.less,.sass,.jpg,.png" cache="true" timestampCdnUrl="true" />
		<add paths="/frontend/*" cache="true" timestampCdnUrl="true" />
		<add paths="/media/*" cache="true" timestampCdnUrl="false" />
		<add paths="/bundles/*" cache="true" timestampCdnUrl="false" />
      </rules> 
    </add> 
  </cacheProfiles> 
</Orckestra.Media.CdnPublisher> 

1. In your browser, open a page with the URLs to media or static website files handled by the caching rules.
2. Check these URLs.

The hostname in the URLs should be that of the CDN endpoint you have configured above. Once the endpoint propagate through the CDN, the files will be available on your website.

Configuring CDN Publisher on a website with extranet

If your website features extranet, consider configuring redirects for the protected C1 media to public websites - in addition to one of the above setup options (Simple or CM / CD).

To redirect protected media files from the CDN source hostname to the public hostname(s):

1. Edit ~/App_Config/Orckestra.Media.CdnPublisher.config
2. Set the redirect for protected media in the <redirects/> element:
   
   • target: set it to "protected_c1media"
   • fromHostname: set it to the hostname of your CDN source (for example, 'cdnsource.orckestra.com')
   • toHostname: set it to the public hostname (for example, 'www.orckestra.com')

Example:

<redirects> 
  <add target="protected_c1media" fromHostname="cdnsource.orckestra.com" toHostname="www.orckestra.com" /> 
</redirects>

To prevent already cached protected files to appear as public on the live website(s):

1. Purge the CDN cache on Azure (recommended).
2. Wait until the endpoint will propagate through the CDN (90 minutes or so).

Editing CDN Publisher configuration

The CDN Publisher's configuration consists of three parts represented by these elements:

• <cdn/>: The CDN parameters. Required.
• <redirects/>: Redirect parameters. Optional.
• <cacheProfiles/>: A set of caching rules for the CDN in use. Required. Defaults provided.

If needed, you can change the configuration parameters.

CDN parameters

When configuring CDN Publisher, you must set the required CDN parameters.

<cdn>
  <add cdnEdgeUrl="//contoso.azureedge.net" enabledOnHosts="*" cacheProfile="shared" />
</cdn>

• cdnEdgeUrl: the CDN endpoint hostname (for example, 'contoso.azureedge.net')
• enabledOnHosts: "*" to use CDN on all hosts, or specific public public hostname(s) (for example, 'www.contoso.com, contoso.com'). Use wildcards if necessary.
• cacheProfile: the name of the cache profile with rules. By default set to "shared", the predefined profile CDN Publisher comes with.

(In most cases, you will do with a single CDN endpoint configured here. You can however have more than one <add/> element within <cdn></cdn> if need be.)

Redirects

The CDN Publisher allows you to do two types of redirects on your website with CDN Publisher:

• redirects for C1 pages
• redirects for protected C1 media

If your website is available via the CDN source hostname (along with the public hostname), it makes sense to prevent visitors from accessing your CDN source website as well as search engines from indexing it. In this case, you should configure redirects for C1 pages form the CDN source to the public website:

<redirects> 
  <add target="c1pages" fromHostname="cdnsource.contoso.com" toHostname="contoso.com" />
</redirects>

• target: it must be set to "c1pages"
• fromHostname: the hostname of your CDN source to redirect requests from (for example, 'cdnsource.orckestra.com')
• toHostname: the hostname of your public website to redirect requests to (for example, 'www.orckestra.com')

If your website has C1 media protected by extranet, you should redirect requests to the protected media to the public website where they will be properly addressed preventing visitors from unauthorized access to the media:

<redirects> 
  <add target="protected_c1media" fromHostname="cdnsource.orckestra.com" toHostname="www.orckestra.com" /> 
</redirects>

• target: it must be set to "protected_c1media"
• fromHostname: the hostname of your CDN source to redirect requests from (for example, 'cdnsource.orckestra.com')
• toHostname: the hostname of your public website to redirect requests to (for example, 'www.orckestra.com')

Please see Configuring CDN Publisher on a website with extranet for more information on redirecting the protected media.

Cache profiles and rules

CDN Publisher comes with a predefined cache profile named "shared" that includes several caching rules:

<add name="shared">
  <rules>
    <add paths=".js,.css,.less,.sass,.jpg,.png" cache="true" timestampCdnUrl="true" />
    <add paths="/frontend/*" cache="true" timestampCdnUrl="true" />
    <add paths="/media/*" cache="true" timestampCdnUrl="false" />
    <add paths="/bundles/*" cache="true" timestampCdnUrl="false" />
  </rules>
</add>

You can add, remove or change the rules in the default cache profile or create a new profile and refer to it in the CDN parameters.

To add and use a new cache profile:

1. Edit ~/App_Config/Orckestra.Media.CdnPublisher.config
2. Within the <cacheProfiles></cacheProfiles> element, add an <add /> element.
3. In its name attribute, specify the name for the profile (for example, "contoso").
4. Below this newly added element, add a <rules></rules> element.
5. Add one or more rules as described further below.
6. Make sure to use this profile in the CDN parameters (... cacheProfile="contoso").

Example:

<?xml version="1.0" encoding="utf-8"?>
<Orckestra.Media.CdnPublisher>
  <cdn>
    <add cdnEdgeUrl="//contoso.azureedge.net" enabledOnHosts="*" cacheProfile="contoso" />
  </cdn>
  <redirects>
  </redirects>
  <cacheProfiles>
    <add name="contoso">
      <rules>
      </rules>
    </add>
  </cacheProfiles>
</Orckestra.Media.CdnPublisher>

To add a rule to the cache profile:

1. Within the <rules></rules> element, add an <add /> element.
2. Set these attributes on the element:
   1. paths: a relative path or file types to apply the rule to. Can contain wildcards.
   2. cache: if "true", the file(s) will be cached on the CDN until expired and used when requested; otherwise ("false"), the version from the CDN source will be used without caching.
   3. timestampCdnUrl: (optional) if "true", a timestamp hash will be appended to the URL of a file, thus making sure that the file's latest version will be retrieved if the file has been changed; otherwise, the cached version from the CDN will be used until expired.

Example:

<rules>
  <add paths=".js,.css,.less,.sass,.jpg,.png" cache="true" timestampCdnUrl="true" />
  <add paths="/frontend/*" cache="true" timestampCdnUrl="true" />
  <add paths="/media/*" cache="true" timestampCdnUrl="false" />
  <add paths="/bundles/*" cache="true" timestampCdnUrl="false" />
</rules>