Configure Virtual Hosts in an Environment - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 12. There's an updated version available that covers our most recent release.

16-07-2018

Configure Virtual Hosts in an Environment

Introduction

Goal

Configure delivery tier virtual hosts after first deployment in an environment.

Background

Bloomreach Experience Manager's delivery tier supports running multiple sites on different host names with cross-domain linking. This requires that virtual hosts are configured at application level.

For more technical background information about the configuration model read Request Matching, Hostname Matching and Mount Matching.

Instructions

The virtual hosts configuration is stored in the content repository and managed using the Console application.

Let's assume Bloomreach Experience Manager has been deployed in a production environment serving one site at https://www.example.com and the CMS application at https://cms.example.com.

  1. The starting point is the default virtual hosts configuration of a Bloomreach Experience Manager project:

    /hst:hst/hst:hosts:
      /dev-localhost:
        jcr:primaryType: hst:virtualhostgroup
        /localhost:
          jcr:primaryType: hst:virtualhost
          /hst:root:
            jcr:primaryType: hst:mount
    

    It configures the virtual host localhost for use in a local development environment.

  2. Create a new virtual host group production-env by adding a node of type hst:virtualhostgroup:

    /hst:hst/hst:hosts:
      /dev-localhost:
        jcr:primaryType: hst:virtualhostgroup
        /localhost:
          jcr:primaryType: hst:virtualhost
          /hst:root:
            jcr:primaryType: hst:mount
      /production-env:
        jcr:primaryType: hst:virtualhostgroup
    
  3. Add the hst:cmslocation property to the production-env node to specify the URL of the CMS application:
    /hst:hst/hst:hosts:
      /dev-localhost:
        jcr:primaryType: hst:virtualhostgroup
        /localhost:
          jcr:primaryType: hst:virtualhost
          /hst:root:
            jcr:primaryType: hst:mount
      /production-env:
        jcr:primaryType: hst:virtualhostgroup
        hst:cmslocation: https://cms.example.com
    
  4. If the site is accessed using an explicit port number (e.g. 8080) in the URL add the hst:defaultport property to the production-env node:
    /hst:hst/hst:hosts:
      /dev-localhost:
        jcr:primaryType: hst:virtualhostgroup
        /localhost:
          jcr:primaryType: hst:virtualhost
          /hst:root:
            jcr:primaryType: hst:mount
      /production-env:
        jcr:primaryType: hst:virtualhostgroup
        hst:cmslocation: https://cms.example.com
        hst:defaultport: 8080
    
    If the site is accessed without an explicit port number in the URL, don't specify the hst:defaultport property at all (skip this step).
  5. In the production-env virtual host group, create a reverse hierarchy of the www.example.com domain using nodes of type hst:virtualhost:
    /hst:hst/hst:hosts:
      /dev-localhost:
        jcr:primaryType: hst:virtualhostgroup
        /localhost:
          jcr:primaryType: hst:virtualhost
          /hst:root:
            jcr:primaryType: hst:mount
      /production-env:
        jcr:primaryType: hst:virtualhostgroup
        hst:cmslocation: https://cms.example.com
        /com:
          jcr:primaryType: hst:virtualhost
          /example:
            jcr:primaryType: hst:virtualhost
            /www:
              jcr:primaryType: hst:virtualhost
  6. Copy the node  hst:hst/hst:hosts/dev-localhost/localhost/hst:root to  hst:hst/hst:hosts/production-env/com/example/www/hst:root to mount the site at the www.example.com virtual host:
    /hst:hst/hst:hosts:
      /dev-localhost:
        jcr:primaryType: hst:virtualhostgroup
        /localhost:
          jcr:primaryType: hst:virtualhost
          /hst:root:
            jcr:primaryType: hst:mount
      /production-env:
        jcr:primaryType: hst:virtualhostgroup
        hst:cmslocation: https://cms.example.com
        /com:
          jcr:primaryType: hst:virtualhost
          /example:
            jcr:primaryType: hst:virtualhost
            /www:
              jcr:primaryType: hst:virtualhost
              /hst:root:
                jcr:primaryType: hst:mount
    
  7. Add the two Boolean properties hst:showport and hst:showcontextpath, both with value false, to the hst:root node:
    /hst:hst/hst:hosts:
      /dev-localhost:
        jcr:primaryType: hst:virtualhostgroup
        /localhost:
          jcr:primaryType: hst:virtualhost
          /hst:root:
            jcr:primaryType: hst:mount
      /production-env:
        jcr:primaryType: hst:virtualhostgroup
        hst:cmslocation: https://cms.example.com
        /com:
          jcr:primaryType: hst:virtualhost
          /example:
            jcr:primaryType: hst:virtualhost
            /www:
              jcr:primaryType: hst:virtualhost
              /hst:root:
                jcr:primaryType: hst:mount
                hst:scheme: https
                hst:showport: false
                hst:showcontextpath: false
    

    Use hst:scheme = https in HTTPS-only scenarios (recommended). Alternatively, use hst:scheme = http for HTTP-only, or hst:schemeagnostic = true to support both HTTP and HTTPS.

    The properties hst:showport and hst:showcontextpath when set to false make sure that the context path and port are not included in links generated by the delivery tier. They can be specified at any level in the virtual hosts configuration and are inherited by child configuration nodes.

  8. Write changes to the repository.
Repeat the steps 5-7 for any additional sites.
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?