Configure Virtual Hosts in an Environment

Overview

This page describes how to configure delivery tier virtual hosts in a Bloomreach Experience Manager environment after the initial deployment.

Background

The delivery tier in Bloomreach Experience Manager supports multiple sites on different hostnames and enables cross-domain linking. Virtual host configuration is stored in the content repository and managed through the Console application.

Info: For details on the configuration model, see Request Matching, Hostname Matching, and Mount Matching.

Configure Virtual Hosts

This example assumes a production deployment with one site at https://www.example.com and the CMS application at https://cms.example.com.

  1. Start with the default virtual hosts configuration for a new 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

    This configuration defines the localhost virtual host for local development.

  2. Add a new virtual host group named production-env by creating 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 group, create a reverse hierarchy for 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 at 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 Boolean properties hst:showport and hst:showcontextpath, both set to false, on 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

    Info: Set hst:scheme = https for HTTPS-only environments (recommended). Use hst:scheme = http for HTTP-only, or hst:schemeagnostic = true to support both protocols.

    Info: Setting hst:showport and hst:showcontextpath to false ensures that generated links do not include the context path or port. You can set these properties at any level in the virtual hosts configuration. Child nodes inherit these settings.

  6. Mirror the new virtual hosts group in the platform configuration 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. Save your changes to the repository.

Hint: Repeat steps 3 and 4 for each additional site you want to configure.

Use System Property Expansion in Virtual Host Configuration

Info: System property expansion is supported starting with Bloomreach Experience Manager 14.2.1.

In many deployment scenarios, such as blue-green deployments, the same distribution is deployed to multiple environments that differ only in hostname. To avoid duplicating virtual host configuration, you can use placeholders in the names of hst:virtualhost nodes. Placeholders use the syntax ${system.property.name} and are dynamically expanded at runtime based on system properties.

Example: Blue-Green Deployment in Bloomreach Cloud

In Bloomreach Cloud, an environment named myenvironment in the namespace mycompany is accessible at myenvironment.mycompany.bloomreach.cloud. In a blue-green deployment, environments might be named blue and green, with hostnames blue.mycompany.bloomreach.cloud and green.mycompany.bloomreach.cloud.

Bloomreach Cloud defines the system properties brc.environmentname and brc.namespace by default. You can use these properties to create generic virtual host configurations.

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
Share Feedback
Page: /deploy/on-premise-deployment/configure-virtual-hosts-in-an-environment
Section: Deploy
Category *
Configure Virtual Hosts in an Environment | Bloomreach Content Documentation