Serve Gallery Images, Assets, Web Files, and Static Webapp Files from a CDN

Overview

This page explains how to configure Bloomreach Content to serve repository gallery items, assets, web files, and static webapp files through a Content Delivery Network (CDN).

When to Use

Use a CDN to serve large or frequently accessed binary files, such as gallery items, assets, web files, or static webapp files. Serving these files from a CDN can reduce bandwidth usage on your origin server and lower latency for end users.

Bloomreach Content supports CDN integration out of the box. You can configure a CDN host per hst:virtualhost and update this configuration in a running production environment.

Prerequisites

• Access to the JCR repository to configure hst:virtualhost nodes.
• A CDN endpoint (host) available for serving static files.

Configure a CDN Host

To configure a CDN host, add the hst:cdnhost property to any hst:virtualhost node under /hst:hst/hst:hosts in the repository.

hst:cdnhost

• The hst:cdnhost property is inherited by child hst:virtualhost nodes unless you explicitly override it.
• To prevent inheritance, add the hst:cdnhost property to the child node and set its value to empty.

The CDN host value must use the following format:

//{cdnhost}

For example, to serve binaries from cdn.example.org, configure:

hst:cdnhost: //cdn.example.org

You can also use formats like //cdn.acct.example.org or //cdn.acct.example.org:8080. Scheme prefixes such as http:// or https:// are supported but not recommended.

Example Configuration

The following example configures production hosts to serve files from a CDN:

/hst:hosts:
  /dev-env:
    jcr:primaryType: hst:virtualhostgroup
    /localhost:
      jcr:primaryType: hst:virtualhost
  /acct-env:
    jcr:primaryType: hst:virtualhostgroup
    /com:
      jcr:primaryType: hst:virtualhost
      /example:
        jcr:primaryType: hst:virtualhost
        /acct:
          jcr:primaryType: hst:virtualhost
      /example2:
        jcr:primaryType: hst:virtualhost
        /acct:
          jcr:primaryType: hst:virtualhost
  /prod-env:
    jcr:primaryType: hst:virtualhostgroup
    /com:
      jcr:primaryType: hst:virtualhost
      hst:cdnhost: //cdn.example.com
      /example:
        jcr:primaryType: hst:virtualhost
        /www:
          jcr:primaryType: hst:virtualhost
      /example2:
        jcr:primaryType: hst:virtualhost
        /www:
          jcr:primaryType: hst:virtualhost
copy

In this configuration, gallery items, assets, web files, and static webapp resources for http://www.example.com and http://www.example2.com are served from http://cdn.example.com.

Technical Details: Why Use // for CDN Hosts

According to RFC3986 section 5.4.1, a relative reference beginning with // inherits the scheme (http or https) of the base URI. For example:

Within a representation with a well defined base URI of

http://a/b/c/d;p?q

a relative reference is transformed to its target URI as follows.

RFC 3986                   URI Generic Syntax               January 2005
5.4.1.  Normal Examples

      "g:h"           =  "g:h"
      "g"             =  "http://a/b/c/g"
      "./g"           =  "http://a/b/c/g"
      "g/"            =  "http://a/b/c/g/"
      "/g"            =  "http://a/g"
      "//g"           =  "http://g"
      "?y"            =  "http://a/b/c/d;p?y"
      "g?y"           =  "http://a/b/c/g?y"
      "#s"            =  "http://a/b/c/d;p?q#s"
      "g#s"           =  "http://a/b/c/g#s"
      "g?y#s"         =  "http://a/b/c/g?y#s"
      ";x"            =  "http://a/b/c/;x"
      "g;x"           =  "http://a/b/c/g;x"
      "g;x?y#s"       =  "http://a/b/c/g;x?y#s"
      ""              =  "http://a/b/c/d;p?q"
      "."             =  "http://a/b/c/"
      "./"            =  "http://a/b/c/"
      ".."            =  "http://a/b/"
      "../"           =  "http://a/b/"
      "../g"          =  "http://a/b/g"
      "../.."         =  "http://a/"
      "../../"        =  "http://a/"
      "../../g"       =  "http://a/g"

The relevant example is:

//g  =  http://g

Using // as a prefix ensures that the CDN host uses the same scheme as the original request. For example, if a user accesses http://www.example.org, files are served from http://cdn.example.org. If the user accesses https://www.example.org, files are served from https://cdn.example.org. This approach avoids mixed content issues and ensures consistent protocol usage.