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.

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

Configure 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:myproject/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:myproject/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:myproject/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:myproject/hst:hosts/dev-localhost/localhost/hst:root to  hst:myproject/hst:hosts/production-env/com/example/www/hst:root to mount the site at the www.example.com virtual host:
    /hst:myproject/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:myproject/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.

Use System Property Expansion in Virtual Host Configuration

This feature is available since Bloomreach Experience Manager 14.2.1.

In most real-world deployment scenarios, for example blue-green deployment, the same distribution gets deployed to multiple environments that are very similar except in hostname. To prevent duplication in virtual host configurations, it is possible to use placeholders in the names of the hst:virtualhost nodes. The placeholders, written as ${system.property.name}, must refer to system properties and are dynamically expanded at runtime.

Example: Blue-Green Deployment in Bloomreach Cloud

In Bloomreach Cloud, an environment 'myenvironment' in a namespace 'mycompany' typically is accessible at the hostname myenvironment.mycompany.bloomreach.cloud. In a blue-green deployment scenario, the environments would be 'blue' and 'green' and the corresponding hostnames blue.mycompany.bloomreach.cloud and green.mycompany.bloomreach.cloud.

Bloomreach Cloud also defines the system properties brc.environmentname and brc.namespace by default. Therefore, when deploying in Bloomreach Cloud, it is possible to use generic virtual host configurations like the following example:

Site virtual host configuration:

/hst:myproject/hst:hosts:
  jcr:primaryType: hst:virtualhosts
  /br-cloud:
    jcr:primaryType: hst:virtualhostgroup
    /cloud:
      jcr:primaryType: hst:virtualhost
      /bloomreach:
        jcr:primaryType: hst:virtualhost
        /${brc.namespace}:
          jcr:primaryType: hst:virtualhost
          /${brc.environmentname}:
            jcr:primaryType: hst:virtualhost
            /hst:root:
              jcr:primaryType: hst:mount
              hst:homepage: root
              hst:mountpoint: /hst:myproject/hst:sites/myproject

Platform virtual host configuration:

/hst:platform/hst:hosts:
  jcr:primaryType: hst:virtualhosts
  /br-cloud:
    jcr:primaryType: hst:virtualhostgroup
    /cloud:
      jcr:primaryType: hst:virtualhost
      /bloomreach:
        jcr:primaryType: hst:virtualhost
        /${brc.namespace}:
          jcr:primaryType: hst:virtualhost
          /${brc.environmentname}:
            jcr:primaryType: hst:virtualhost
            /hst:root:
              jcr:primaryType: hst:mount
              hst:ismapped: false
              hst:namedpipeline: WebApplicationInvokingPipeline

 

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?