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

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.

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

Virtual host can be either static or, as of version 13.1, runtime. Static virtual hosts require more configuration upfront but provide full control and can support more complex use cases. Runtime virtual hosts require less configuration but also provide less control so they are best suited for typical, straightforward use cases.

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

Static Virtual Hosts

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. 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
        /com:
          jcr:primaryType: hst:virtualhost
          /example:
            jcr:primaryType: hst:virtualhost
            /www:
              jcr:primaryType: hst:virtualhost
  4. 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
        /com:
          jcr:primaryType: hst:virtualhost
          /example:
            jcr:primaryType: hst:virtualhost
            /www:
              jcr:primaryType: hst:virtualhost
              /hst:root:
                jcr:primaryType: hst:mount
    
  5. 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
        /com:
          jcr:primaryType: hst:virtualhost
          hst:scheme: https
          hst:showport: false
          hst:showcontextpath: false
          /example:
            jcr:primaryType: hst:virtualhost
            /www:
              jcr:primaryType: hst:virtualhost
              /hst:root:
                jcr:primaryType: hst:mount
    

    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.

  6. Mirror the new virtual hosts group in the platform configuration in order to define the CMS mount:
    /hst:platform/hst-hosts/production-env:
      jcr:primaryType: hst:virtualhostgroup
      /com:
        jcr:primaryType: hst:virtualhost
        hst:scheme: https
        hst:showport: false
        hst:showcontextpath: false
        /example:
          jcr:primaryType: hst:virtualhost
          /cms:
            jcr:primaryType: hst:virtualhost
            /hst:root:
              jcr:primaryType: hst:mount
              hst:ismapped: false
              hst:namedpipeline: WebApplicationInvokingPipeline
    
  7. Write changes to the repository.
Repeat steps 3 and 4 for additional sites.

Runtime Virtual Hosts

This feature is available since version 13.1.

By using runtime virtual hosts, it is possible to access to the CMS application and the sites without adding virtual host configurations.

For example, if the site is served on https://www.example.com and the CMS application is served on https://cms.example.com, the configuration below should be added.

/hst:platform/hst:hosts:
  /dev-localhost:
    jcr:primaryType: hst:virtualhostgroup
    hst:autohosttemplate: ['https://www.example.com', 'https://cms.example.com']
    /localhost:
      jcr:primaryType: hst:virtualhost
      /hst:root:
        jcr:primaryType: hst:mount

By using this configuration, the requests made to https://www.example.com and https://cms.example.com will use /dev:localhost as their virtual host group. They will create their own virtual hosts by using /localhost and and their mounts by using /hst:root at runtime.

The runtime virtual host definition of the CMS application will be:

/hst:platform/hst:hosts:
  /dev-localhost:
    jcr:primaryType: hst:virtualhostgroup
    /com:
      jcr:primaryType: hst:virtualhost
      /example:
        jcr:primaryType: hst:virtualhost
        /cms:
          jcr:primaryType: hst:virtualhost
          /hst:root:
            jcr:primaryType: hst:mount

The runtime virtual host definition of the site will be:

/hst:myproject/hst:hosts:
  /dev-localhost:
    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

These definitions are only runtime definitions, so they will not be persisted. That means, at every restart of the application, these definitions will be vanished. To maintain the consistency of using runtime virtual hosts, it is suggested to use /dev:localhost to define the hst:autohosttemplate property.

The hst:autohosttemplate property is a string array which contains allowed runtime host URL patterns. That means several runtime host URL patterns can be used at the same time.

It is allowed to use asterisk (*) in URLs. Only one asterisk can be used in a URL and it must be in the first part of the URL after the scheme section.

Virtual host properties hst:scheme and hst:showport are decided from the URL pattern. If the URL starts with https, then hst:scheme will be set as https, otherwise http will be set. If the port number is defined at the end of the URL, then hst:showport property will be set as true.

Valid runtime URL patterns are listed below:

https://*-site.com
https://site-*.com
https://*.com
https://*.example.com
https://site.example.com
https://*-eng.com:8080
https://example.com:8080

Invalid runtime URL patterns are listed below:

https://*
https://site.*.com
https://*.*.com
https://com
https://site-*
https://site.*
https://*-site.com:aa
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?