Hostname Matching

During the hostname matching phase, Bloomreach Content attempts to match the hostname from the HttpServletRequest to a configured virtualhost in the HST configuration. The value used for the hostname is taken from the Host header, or from the X-Forwarded-Host header if it is present. This approach ensures that the original host information requested by the client is used.

Virtual hosts are configured in a reversed hierarchy. The following example shows a typical configuration:

/hst:hst:
  /hst:hosts:
    jcr:primaryType: hst:virtualhosts
    /dev-localhost:
      jcr:primaryType: hst:virtualhostgroup
      /localhost:
        jcr:primaryType: hst:virtualhost
    /test-env:
      jcr:primaryType: hst:virtualhostgroup
      /com:
        jcr:primaryType: hst:virtualhost
        /example:
          jcr:primaryType: hst:virtualhost
          /test:
            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
    /prod-env:
      jcr:primaryType: hst:virtualhostgroup
      /com:
        jcr:primaryType: hst:virtualhost
        /example:
          jcr:primaryType: hst:virtualhost
          /www:
            jcr:primaryType: hst:virtualhost
copy

This configuration defines:

1. Four environments, each represented by a virtualhostgroup: dev-localhost, test-env, acct-env, and prod-env. Environments are separated to support cross-domain linking within the same environment, while preventing links between different environments. The HST will not generate links that cross between virtualhostgroups. For example, a link from www.example.com (in prod-env) will not resolve to acct.example.com (in acct-env).

2. The following hostnames are available in this configuration:

   localhost
   test.example.com
   acct.example.com
   www.example.com
   

Note that example.com and com are also valid hostnames in the hierarchy. However, a host is only matched by the HST if there is a hst:root node of type hst:mount beneath it. For example, if you add a hst:root node under:

/hst:hst/hst:hosts/com/example
copy

then example.com becomes a valid host for matching.

To support additional top-level domains, such as .fr, update the host configuration as shown below:

/hst:hst:
  /hst:hosts:
    jcr:primaryType: hst:virtualhosts
    /dev-localhost:
      jcr:primaryType: hst:virtualhostgroup
      /locahost:
        jcr:primaryType: hst:virtualhost
    /test-env:
      jcr:primaryType: hst:virtualhostgroup
      /com:
        jcr:primaryType: hst:virtualhost
        /example:
          jcr:primaryType: hst:virtualhost
          /test:
          jcr:primaryType: hst:virtualhost
      /fr:
        jcr:primaryType: hst:virtualhost
        /example:
          jcr:primaryType: hst:virtualhost
          /test:
            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
      /fr:
        jcr:primaryType: hst:virtualhost
        /example:
          jcr:primaryType: hst:virtualhost
          /acct:
            jcr:primaryType: hst:virtualhost
    /prod-env:
      jcr:primaryType: hst:virtualhostgroup
      /com:
        jcr:primaryType: hst:virtualhost
        /example:
          jcr:primaryType: hst:virtualhost
          /www:
            jcr:primaryType: hst:virtualhost
       /fr:
         jcr:primaryType: hst:virtualhost
         /example:
           jcr:primaryType: hst:virtualhost
           /www:
             jcr:primaryType: hst:virtualhost
copy

The .com hosts remain unchanged, and .fr hosts are added. With this configuration, the following additional hostnames are available:

test.example.fr
acct.example.fr
www.example.fr

No .fr host is added for localhost. For local development, you typically access all sites using localhost. For details on how mount matching works in local development, see Mount Matching.

Properties on a VirtualHost

The following table describes key properties available on a VirtualHost node:

Property name	Example	Description
hst:responseheaders	["Access-Control-Allow-Origin: http://localhost:3000", "Access-Control-Allow-Credentials: true"]	Custom HTTP response headers that are always set for requests on this virtual host, its descendant mounts, and sitemap items, unless overridden. Use this property to configure headers required for Cross-Origin Resource Sharing (CORS) or other scenarios. Set this property as a string array, where each entry uses the format <header_name>:<header_value>.
hst:allowedorigins Available since v14.1.0	["http://www.example.com", "http://localhost:3000"]	List of origins allowed to make cross-origin requests. When an allowed origin makes a request, the Access-Control-Allow-Origin response header is set to that origin. If Access-Control-Allow-Origin is defined in hst:responseheaders, this property is ignored. Set this property as a string array, with each entry in the format <protocol>://<hostname>:<port>.
hst:linkurlprefix Available since v14.2.1	https://www.example.org	URI scheme, authority, and optional path used to prefix fully qualified internal links.
hst:cdnhost	//cdn.example.org	CDN host used to serve static and binary files. For more information, see Serve Gallery Images, Assets, Web Files, and Static Webapp Files from a CDN. If both hst:linkurlprefix and hst:cdnhost are present, hst:cdnhost takes precedence.