Hosts Configuration
This part of the configuration contains the information for host and mount (sub site/channel) matching. The hosts information for the Platform application and all Site web applications is stored in the repository. The HST supports multiple hosts within a single Site application, and since the host information for all the available sites is stored in the repository, webmasters can add new hosts in a running production environment. This is done through the Experience manager making use of Blueprints.
Hosts configuration for the Platform application
For each Virtual Host Group, the CMS/platform web application must define the mount point of the CMS below /hst:platform in the repository. For example, if the production environment CMS shall be exposed at https://cms.myproject.com, the corresponding mount definition looks like this:
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
In order to mark the mount as a "CMS mount", set these properties:
- hst:ismapped = false
- hst:namedpipeline = WebApplicationInvokingPipeline
If you want to use the HTTPS scheme, set the hst:scheme property on the highest feasible virtual host node. In above example, this is the "com" node. Likewise if the contextpath or portnumber is not visible in the URL, then set hst:showcontextpath and hst:showport to false.
Make sure you configure the correct CMS mounts for all Virtual Host Groups (e.g. test, staging, production).
Missing Platform CMS Host
If no matching host for the CMS can be found, for example when the CMS can be reached at http://cms.myproject.com, but below /hst:platform there is no matching hosts configuration, then the CMS will be accessible, but parts will not function properly. For example no Channels will be shown in the Experience manager, the [view] button in the document editor won't show channels and neither will Relevance nor Projects will work correctly.
Fail-Safe HstMode in case of being locked out from the CMS (and Console)
When modifying the /hst:platform configuration via Console it is possible to lock yourself out from the CMS and the Console. The reason is that by default all application requests, including requests to the CMS or Console are first passed through the Platform application. If for example you change the hst:namedpipeline into a different pipeline, or a non-existing one, the CMS and Console will become unreachable. Or if you can only access the CMS over https, but you forget to add the correct hst:scheme configuration, you’ll get an error about too many redirections, making the Console unavailable and locking you out from correcting your mistake.
To fix this, add a HstMode=false request parameter to the CMS or Console URL, for example:
https://cms.myproject.com/console?HstMode=false
The above will trigger for your session that the CMS runs without the Platform for all subsequent requests, until you request:
https://cms.myproject.com/console?HstMode=true
Until the HstMode is switched on again, the CMS runs without HST matching. Certain features in the CMS, such as the Experience manager, Relevance or Projects won't work correctly. Note that is is valid for your session only, not for the sessions of other users.
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 will only show sites in the Experience manager of hosts groups with the same name that the CMS URL is matched to. With the hosts configuraton example shown above, the site that is served on https://www.myproject.com can be shown in the Experience manager of the CMS application that can be reached on https://cms.myproject.com because their hosts are configured in a group with the same name. If there is no matching host group available, maybe due to misconfiguration, the CMS will work but no Channels can be displayed.
The purpose of Host Groups
To support a single host configuration quarantined between local development, test, acceptance and production environments, the first nodes below the hst:hosts node are the hostgroup nodes which are of type hst:virtualhostgroup. The goal of a virtualhostgroup is to group hosts that can cross link to each other, but not across hostgroups: The HST will never create a link between for example test and production environment this way. After the hostgroup nodes, the host nodes follow, and finally the mount nodes. Hosts are hierarchically configured in reversed order, unless they are an ip-address. An example hst:hosts configuration without mounts looks like:
/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
After a host node, to make the host really available for HST matching, an hst:mount node needs to be configured with the name hst:root. The hst:root mount is interpreted as ‘ /’. Below an hst:root mount node, descendant mounts can be configured: These are sub-sites below a host. Adding mounts to the host configuration example above (and ignore test-env, test-ip-env and acct-env for simplicity) results in for example:
/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
Now, the following hosts and sub-channels are available (ignoring ports):
dev-env:
- http://localhost/
- http://localhost/test2
prod-env:
- http://www.example.com/
- http://www.example2.com/
When a request hits a Site application, the request is first matched against the host and mount configuration. See HostName Matching and Mount Matching for an explanation of how the matching rules work. In a nutshell, a request is matched to the best possible matching host and mount.
Then, on a hst:mount node a developer must configure the following property:
hst:mountpoint : path to an hst:site node for the request
This links the matched host and mount to site configuration.
*The hst:mountpoint can in exceptional setups also point directly to a content location below /content/documents. Then that mount is not mapped via an hst:sitemap and does not have HMVC rendering. This might be useful for example for REST endpoints that do not need a mapping. Or for example for PDF generation of repository content.
The HST application now knows for the request which hst:site and which hst:channel to use to proceed the request handling with. See Sites & Channels configuration for a further explanation.