Bloomreach

Bloomreach Documentation version

Configure Domains

Introduction

Goal

Direct incoming traffic for a domain to the appropriate environment and webapp.

Background

The domain configuration allows Bloomreach Cloud to route incoming traffic for a domain name to the appropriate environment. This is very useful when using the blue-green deployment model. Changing the environment reference in Mission Control is sufficient to direct traffic to the other environment with immediate effect.

You have two options for adding new domains or sub-domains;

Using your reserved bloomreach.cloud URL segment (Option 1)

Each Bloomreach Cloud stack will have a reserved URL segment ex. *.customer.bloomreach.cloud.  For example, a customer with stack name bankpoc, will have *.bankpoc.bloomreach.cloud url segment reserved.
bloomreach.cloud customer domains can be added either via Mission Control UI, or Bloomreach Cloud API. 

Some examples of domains for customer "bankpoc":

blue.bankpoc.bloomreach.cloud

green.bankpoc.bloomreach.cloud

dev.bankpoc.bloomreach.cloud

test.bankpoc.bloomreach.cloud

Using your own provided domain or sub-domain (Option 2)

Example, www.customer.com. 

It is also possible to request a wildcard such as *.customer.com in which case you will be able to add any third level sub-domain.
Do not use the CMS (sub)domain to access the site webapp / delivery API. Always use different (sub)domains (e.g. cms.customer.com and prod.customer.com) to ensure public availability of your website(s) is not affected when CMS maintenance mode is enabled.

Prerequisites and Constraints

For both Option 1 and Option 2:

  • Make sure you have created a distribution and you have at least 1 environment deployed in the Mission Control.

  • Before adding a domain, the delivery tier for your environment must have a corresponding virtual host configuration for that specific domain.

  • If you do not want caching enabled for any reason, please reach out to our support team and request that the caching is turned off for your domain. To understand our default caching behaviour please go to official Cloudflare documentation. Bloomreach Cloud is integrated with Cloudflare "Enterprise" tier solution.

Only valid for Option 1:

  • You sub-domain and environments cannot share the same name. For example, you cannot add blue.customer.bloomreach.cloud domain if you have environment named "blue" in your mission control. This will fail because the platform will already generate few links for you automatically (Site, CMS, Console and Repository).
Do not auto-generated links for anything except for innitial configuration and quick testing. For dev/test and production environments always use "user managed domain".  (Option 1 or Option 2)

Only valid for Option 2:

  • Bloomreach Cloud platform exposes Websites and API's to the internet through the usage of Elastic Load Balancers. Since AWS ELB's rely on DNS based load balancing, Bloomreach Cloud can only provide you with a CNAME record to resolve the ELB's addresses which can change over time. This can potentially be an issue if you are trying to add your own apex domain (also called bare, naked, or root domains) due to the limitations of DNS A-records . This can however be avoided by using a sub-domain, such as www.customer.com and configuring your apex domain  ex. customer.com to re-direct against it. If your DNS registrar does not provide redirect functionality for your apex domain, please reach out to support for assistance. 
  • When adding your own domain, Bloomreach Cloud will provide an option to manage your SSL certificates through DigiCert certificate authority. Please note that you will be required to add TXT validation record in your domain registrar in order to prove domain ownership.  You can however provide your own certificate if you wish to do that by raising a support request. For instructions on how to share your certificate please follow the guide: Provide SSL certificate.
When providing your own SSL certificates, you will be expected to provide new cert bundle at least 7 days before the installed certificates expire.

Instructions

Configure a New Domain

For Option 1:

There is no additional work involved if you plan to use your bloomreach.cloud reserved sub-domains.  You can start adding the reserved domain immediately via Mission Control UI or Bloomreach Cloud API. 

We recommmend using bloomreach.cloud reserved sub-domain for use-case where domain name appearance is not particularly important i.e. headless/SPA implementations.

For Option 2:

In case you would like to use your own domain, you are required to open a support request with the following information:

  1. Case subject: Ex: Custom domain request
  2. Case description with the following information:
    • Domain name. Example: A wildcard domain: *.customer.com
    • Certificate management: "Fully managed with DigiCert CA" (default option), or your own provided certificate). Example: Preferred CA: Fully managed with DigiCert
    • Caching (Enabled / Disabled): Example: Caching: Enabled
    • Attachments: If preferred certificate management is a private cert, please follow the guide: Provide SSL certificate and attach the encrypted certs to the support case.

Make sure to configure the virtual host for the domain in the environment to which you want traffic for that domain to be directed. Example domain: somesubdomain.customer.com

Make sure you have access to your domain registrar because you will be asked to add validation TXT dns records, in case you decide to go for fully managed certificates option.

Add a CNAME record in your DNS registrar as seen below:

somesubdomain.customer.com. 300 IN CNAME    api.<your-stack-name>.bloomreach.cloud

If you are not sure what your api domain is, you can request this information in the support request.

From this point on, after the configurations are done, support team will send you instructions:

  • In case you provided your own certificate, support will notify you after the certificates are validated and sucesfully installed. 
  • In case you decided to go for any of the fully managed certificate options, you will be asked to add a validation TXT dns record in your domain registrar to prove domain ownership.

After receiving the confirmations Log in to Mission Control and navigate to Domains.

Click on the + button in the bottom right corner to add a domain.

Enter the domain name  (for example, somesubdomain.customer.com) and select the environment to which you want traffic for that domain to be directed.

If you would like to serve site traffic please leave the default values for Target context path (/) and Source context path /site unless you are running multiple site webapps (see below).

In case you would like to add a custom domain for your CMS access (for example, cms.customer.com)  leave Source context path at its default value (/) and set Target context path to /cms.

Click on Save.

Switch Domain Between Blue and Green Environments

Make sure the environment you want to switch the domain to has the corresponding virtual host configured.

Log in to Mission Control and navigate to Domains.

Select the domain you want to switch.

In the Environment dropdown, select the environment you want to switch to.

Click on Save.

Do the same for the corresponding domain for the CMS application in case you have CMS domain configured.

Configure Domains for Multipe Site Webapps

In case of multiple site webapps running in one environment, for each additional site webapp, configure an additional domain and source and target context paths.

The configured source context path will be the path after the domain name in the URL browser clients should use to request the site.

The configured target context path will be the actual context path of the webapp.

The source should be either empty or the same as the target. By default, an empty source path (/) is mapped to the target path /site.

For example, if you add a second site webapp called webshop to the example above (cms.customer.com and somesubdomain.customer.com), add another domain for somesubdomain.customer.com but with source path webshop and target path webshop. This will make the webshop site webapp available at somesubdomain.customer.com/webshop/.

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?