Hosts Configuration

The hosts configuration defines how Bloomreach Content matches incoming requests to hosts and mounts (subsites or channels). All host and mount information for both the Platform application and Site web applications is stored in the repository. The HST supports multiple hosts within a single Site application. Because host configuration is stored centrally, you can add or update hosts in a running production environment using the Experience manager and Blueprints.

Hosts Configuration for the Platform Application

For each virtual host group, the CMS (Platform application) must define its mount point under /hst:platform in the repository. For example, to expose the CMS in the production environment at https://cms.myproject.com, configure the following:

definitions:
  config:
    /hst:platform/hst:hosts/prod-env:
      jcr:primaryType: hst:virtualhostgroup
      /com:
        jcr:primaryType: hst:virtualhost
        hst:scheme: https
        hst:showcontextpath: false
        hst:showport: false
        /myproject:
          jcr:primaryType: hst:virtualhost
          /cms:
            jcr:primaryType: hst:virtualhost
            /hst:root:
              jcr:primaryType: hst:mount
              hst:ismapped: false
              hst:namedpipeline: WebApplicationInvokingPipeline

To mark the mount as a CMS mount, set these properties:

  • hst:ismapped: false
  • hst:namedpipeline: WebApplicationInvokingPipeline

To use HTTPS, set the hst:scheme property on the highest applicable virtual host node (in the example above, the com node). If the context path or port number should not appear in the URL, set hst:showcontextpath and hst:showport to false.

Configure the correct CMS mounts for all virtual host groups in your environments (such as test, staging, and production).

Info: By default, the CMS mount for the dev-localhost virtual host group is configured, making the CMS available at http://localhost:8080/cms.

Missing Platform CMS Host

If the CMS is accessible at a URL (for example, http://cms.myproject.com) but there is no matching host configuration under /hst:platform, the CMS will load, but key features will not function. For example, the Experience manager will not display any channels, the document editor's [view] button will not show channels, and features such as Relevance and Projects will not work.

Fail-Safe HstMode When Locked Out of the CMS or Console

When editing /hst:platform configuration in the Console, it is possible to misconfigure the system and lose access to the CMS and Console. This can occur if you change the hst:namedpipeline to an invalid value or omit required properties such as hst:scheme for HTTPS. In these cases, you may encounter errors such as too many redirects, making the Console unavailable.

To regain access, add the HstMode=false request parameter to the CMS or Console URL. For example:

https://cms.myproject.com/console?HstMode=false

This disables HST matching for your session, allowing you to access the CMS or Console and correct the configuration. HST matching remains disabled for your session until you explicitly re-enable it:

https://cms.myproject.com/console?HstMode=true

While HST matching is disabled, features such as the Experience manager, Relevance, and Projects will not function. This setting only affects your session.

Info: If a request reaches the CMS/platform application and no matching host is found, the CMS operates as if HstMode is set to false (no HST matching). In this state, the Experience manager cannot display any channels.

Matching Host Groups Between Platform and Site Applications

/hst:platform
  /hst:hosts
    /prod-env
      /com
        /myproject
          /cms
            /hst:root
/hst:myproject
  /hst:hosts
    /prod-env
      /com
        /myproject
          /www
            /hst:root

The CMS only displays sites in the Experience manager for host groups with the same name as the group matched by the CMS URL. In the example above, the site served at https://www.myproject.com is visible in the Experience manager of the CMS at https://cms.myproject.com because both are configured under the prod-env host group. If the host group names do not match, the CMS will operate but no channels will be displayed.

Purpose of Host Groups

Host groups separate host configurations for different environments such as development, test, acceptance, and production. The first nodes below hst:hosts are host group nodes of type hst:virtualhostgroup. Host groups ensure that cross-linking between environments does not occur; for example, the HST will not generate links from test to production.

After the host group nodes, configure host nodes and then mount nodes. Hosts are defined hierarchically in reverse order, unless the host is an IP address. The following example shows a hst:hosts configuration without mounts:

/hst:hosts:
  jcr:primaryType: hst:virtualhosts
  /dev-env:
    jcr:primaryType: hst:virtualhostgroup
    /localhost:
      jcr:primaryType: hst:virtualhost
  /test-ip-env:
    jcr:primaryType: hst:virtualhostgroup
    /81.21.138.121:
      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
      /example2:
        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
      /example2:
        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
      /example2:
        jcr:primaryType: hst:virtualhost
        /www:
          jcr:primaryType: hst:virtualhost

To make a host available for HST matching, add an hst:mount node named hst:root (which represents the path /*). You can configure sub-mounts under hst:root for sub-sites. The following example adds mounts to the previous configuration (omitting test-env, test-ip-env, and acct-env for clarity):

/hst:hosts:
  jcr:primaryType: hst:virtualhosts
  /dev-env:
    jcr:primaryType: hst:virtualhostgroup
    /localhost:
      jcr:primaryType: hst:virtualhost
      /hst:root:
        jcr:primaryType: hst:mount
        /test2:
          jcr:primaryType: hst:mount
  /prod-env:
    jcr:primaryType: hst:virtualhostgroup
    /com:
      jcr:primaryType: hst:virtualhost
      /example:
        jcr:primaryType: hst:virtualhost
        /www:
          jcr:primaryType: hst:virtualhost
          /hst:root:
            jcr:primaryType: hst:mount
      /example2:
        jcr:primaryType: hst:virtualhost
        /www:
          jcr:primaryType: hst:virtualhost
          /hst:root:
            jcr:primaryType: hst:mount

With this configuration, the following hosts and sub-channels are available (excluding ports):

dev-env:

  1. http://localhost/
  2. http://localhost/test2

prod-env:

  1. http://www.example.com/
  2. http://www.example2.com/

When a request reaches a Site application, the HST matches the request against the host and mount configuration. For details on matching rules, see HostName Matching and Mount Matching. The request is matched to the most specific host and mount.

On each hst:mount node, set the following property:

hst:mountpoint : path to an hst:site node for the request

This property links the matched host and mount to the appropriate site configuration.

The hst:mountpoint property can, in exceptional cases, point directly to a content location under /content/documents. In this scenario, the mount is not mapped via an hst:sitemap and does not use HMVC rendering. This approach is useful for REST endpoints that do not require mapping, or for generating PDFs from repository content.

The HST application uses the matched hst:site and hst:channel to process the request. For more information, see Sites & Channels configuration.

Share Feedback
Page: /about/for-architects/delivery-framework/hosts-configuration
Section: About
Category *